cleveragents/cleveragents-core

Fork 3

UAT: MCPToolAdapter.infer_capabilities() ignores MCP 1.4.0 tool annotations (readOnlyHint, destructiveHint) — capability inference is heuristic-only #4813

New issue

Open

opened 2026-04-08 19:35:53 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-08 19:35:53 +00:00

Owner

Bug Report

Feature Area: MCP Tool Adapter — capability metadata inference
Severity: Medium — MCP tools may be misclassified as read-only or write-capable
Found by: UAT tester instance uat-worker-tool-skill-system
Spec reference: docs/specification.md §MCPToolAdapter — capability metadata

What Was Tested

Code-level analysis of src/cleveragents/mcp/adapter.py — MCPToolAdapter.infer_capabilities() static method.

Expected Behavior (from spec)

MCP 1.4.0 defines standard tool annotations including readOnlyHint (bool) and destructiveHint (bool) that servers can use to declare tool capabilities. The adapter should use these annotations when available to accurately determine read_only and writes capabilities, falling back to name-based heuristics only when annotations are absent.

Actual Behavior

MCPToolAdapter.infer_capabilities() uses only name-based keyword heuristics and completely ignores the annotations field from MCPToolDescriptor:

# src/cleveragents/mcp/adapter.py
@staticmethod
def infer_capabilities(tool_name: str) -> dict[str, bool]:
    """Infer ToolCapability metadata from an MCP tool name.

    Applies heuristics from the specification:
    - Names containing read/get/list/search/find -> read_only
    - Names containing write/create/update/delete/set -> writes
    """
    lower = tool_name.lower()
    read_keywords = {"read", "get", "list", "search", "find"}
    write_keywords = {"write", "create", "update", "delete", "set"}

    parts = set(lower.replace("-", "_").split("_"))

    is_read = bool(parts & read_keywords)
    is_write = bool(parts & write_keywords)
    # ← No use of annotations at all

The MCPToolDescriptor already has an annotations field:

class MCPToolDescriptor(BaseModel):
    name: str
    description: str
    input_schema: dict[str, Any]
    annotations: dict[str, Any]  # ← Contains readOnlyHint, destructiveHint

But infer_capabilities() only takes tool_name: str as input — it doesn't even receive the descriptor.

Impact

MCP tools that use standard annotations to declare their capabilities will be misclassified:

A tool named execute_query with annotations={"readOnlyHint": true} will be classified as writes=False, read_only=False (neither keyword matches) instead of read_only=True
A tool named list_files with annotations={"destructiveHint": true} will be classified as read_only=True instead of writes=True

This can lead to:

Write-capable tools being allowed in read-only plans
Read-only tools being blocked in read-only plans unnecessarily

Code Location

src/cleveragents/mcp/adapter.py — MCPToolAdapter.infer_capabilities() and MCPToolAdapter.register_tools().

Fix

Change infer_capabilities() to accept the full MCPToolDescriptor and check annotations first:

@staticmethod
def infer_capabilities(descriptor: MCPToolDescriptor) -> dict[str, bool]:
    annotations = descriptor.annotations
    
    # Prefer explicit annotations over heuristics
    if "readOnlyHint" in annotations:
        read_only = bool(annotations["readOnlyHint"])
        writes = not read_only
        return {"read_only": read_only, "writes": writes}
    
    if "destructiveHint" in annotations:
        writes = bool(annotations["destructiveHint"])
        return {"read_only": not writes, "writes": writes}
    
    # Fall back to name-based heuristics
    lower = descriptor.name.lower()
    ...

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: uat-tester

## Bug Report **Feature Area:** MCP Tool Adapter — capability metadata inference **Severity:** Medium — MCP tools may be misclassified as read-only or write-capable **Found by:** UAT tester instance `uat-worker-tool-skill-system` **Spec reference:** `docs/specification.md` §MCPToolAdapter — capability metadata --- ### What Was Tested Code-level analysis of `src/cleveragents/mcp/adapter.py` — `MCPToolAdapter.infer_capabilities()` static method. ### Expected Behavior (from spec) MCP 1.4.0 defines standard tool annotations including `readOnlyHint` (bool) and `destructiveHint` (bool) that servers can use to declare tool capabilities. The adapter should use these annotations when available to accurately determine `read_only` and `writes` capabilities, falling back to name-based heuristics only when annotations are absent. ### Actual Behavior `MCPToolAdapter.infer_capabilities()` uses **only name-based keyword heuristics** and completely ignores the `annotations` field from `MCPToolDescriptor`: ```python # src/cleveragents/mcp/adapter.py @staticmethod def infer_capabilities(tool_name: str) -> dict[str, bool]: """Infer ToolCapability metadata from an MCP tool name. Applies heuristics from the specification: - Names containing read/get/list/search/find -> read_only - Names containing write/create/update/delete/set -> writes """ lower = tool_name.lower() read_keywords = {"read", "get", "list", "search", "find"} write_keywords = {"write", "create", "update", "delete", "set"} parts = set(lower.replace("-", "_").split("_")) is_read = bool(parts & read_keywords) is_write = bool(parts & write_keywords) # ← No use of annotations at all ``` The `MCPToolDescriptor` already has an `annotations` field: ```python class MCPToolDescriptor(BaseModel): name: str description: str input_schema: dict[str, Any] annotations: dict[str, Any] # ← Contains readOnlyHint, destructiveHint ``` But `infer_capabilities()` only takes `tool_name: str` as input — it doesn't even receive the descriptor. ### Impact MCP tools that use standard annotations to declare their capabilities will be misclassified: - A tool named `execute_query` with `annotations={"readOnlyHint": true}` will be classified as `writes=False, read_only=False` (neither keyword matches) instead of `read_only=True` - A tool named `list_files` with `annotations={"destructiveHint": true}` will be classified as `read_only=True` instead of `writes=True` This can lead to: - Write-capable tools being allowed in read-only plans - Read-only tools being blocked in read-only plans unnecessarily ### Code Location `src/cleveragents/mcp/adapter.py` — `MCPToolAdapter.infer_capabilities()` and `MCPToolAdapter.register_tools()`. ### Fix Change `infer_capabilities()` to accept the full `MCPToolDescriptor` and check annotations first: ```python @staticmethod def infer_capabilities(descriptor: MCPToolDescriptor) -> dict[str, bool]: annotations = descriptor.annotations # Prefer explicit annotations over heuristics if "readOnlyHint" in annotations: read_only = bool(annotations["readOnlyHint"]) writes = not read_only return {"read_only": read_only, "writes": writes} if "destructiveHint" in annotations: writes = bool(annotations["destructiveHint"]) return {"read_only": not writes, "writes": writes} # Fall back to name-based heuristics lower = descriptor.name.lower() ... ``` --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 referenced this issue

2026-04-08 19:38:31 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 referenced this issue

2026-04-08 19:59:07 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 referenced this issue

2026-04-08 20:12:39 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 referenced this issue

2026-04-08 20:22:25 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 added the

labels

2026-04-08 23:00:07 +00:00

HAL9000 commented

2026-04-09 03:03:17 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Medium — spec compliance bug identified by UAT testing
Story Points: 3 (M) — targeted fix to align implementation with spec
MoSCoW: Must Have — spec compliance is required for correct system behavior

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium — spec compliance bug identified by UAT testing - **Story Points**: 3 (M) — targeted fix to align implementation with spec - **MoSCoW**: Must Have — spec compliance is required for correct system behavior --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner

HAL9000 added

and removed

labels

2026-04-09 03:03:19 +00:00

HAL9000 added this to the v3.5.0 milestone