Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description explains execution modes (sync/async) and outcome reporting, adding context beyond annotations. However, annotations declare readOnlyHint:true and destructiveHint:false, which contradict the tool's likely side effects (performing tasks). This inconsistency is not addressed. Score lowered due to contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise and front-loaded. Every sentence serves a purpose: stating the action, when to use, how to summarize, and error handling. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the annotations and schema, the description covers usage scenarios, behavioral notes (sync/async), and result summarization. It lacks output schema details but that is not required. Could be more explicit about error handling format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the description does not need to add much. It reiterates the high-level purpose but does not elaborate on parameter nuances beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Delegate a multi-step task...to the full agentic planner.' It provides examples (research, composing) and usage condition ('when a user ask needs more than a direct answer'). It distinguishes from simple direct-answer tools but does not explicitly name sibling tools like agents_ask.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit guidance: 'Use when a user ask needs more than a direct answer.' It also instructs on how to summarize outcomes and handle timeout/error statuses. However, it lacks exclusions or explicit alternatives, which would make it a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true and destructiveHint=false. Description adds that traces are retained 30 days, defaults to last 24h, and timezone handling. No contradictions; additional context is useful.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is concise, front-loaded with purpose, and well-structured. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, description explains return contents (messages, documents, calls, summary). Covers defaults, retention, and timezone. Complete for a read-only activity tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%. Description adds practical guidance: how to format since/until (ISO datetime or plain date), how to compute them, and when to omit agent. Adds significant value beyond schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool retrieves activity (messages, documents, calls, summary) for the current agent or another agent. It distinguishes itself from sibling tools like agents_traces_list by focusing on a broader activity summary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit use cases ('what did I do today?') and parameter usage (omit agent for self, since/until formats). Does not explicitly contrast with alternatives, but context is clear enough for correct invocation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate the tool is not read-only and not destructive. The description goes beyond annotations by explaining the asynchronous nature: 'chunk_count — shows 0 while still processing' and the need to poll via agents.list_files. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: first sentence states purpose, then a clear numbered workflow, then a note about the return value. Every sentence is informative and there is no redundant text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description adequately explains the return value and its interpretation. It covers the workflow and prerequisites. However, it does not address idempotency (idempotentHint false) or potential errors, which would make it more complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with descriptions for both parameters. The description adds value by explaining the workflow connecting file_id to prior steps (files_upload/files_ingest) and the significance of the return value (chunk_count). This additional context justifies a score above the baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Attach a file to this agent's private knowledge,' which is a specific verb+resource. It distinguishes itself from sibling tools like agents_remove_file and agents_list_files by emphasizing agent-specific, non-shared files.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear three-step workflow (upload, ingest, then call this tool) and advises checking agents.list_files for final status. It implicitly guides when to use this tool (after upload/ingest) but does not explicitly mention when not to use it or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate non-readonly and non-destructive behavior. The description adds critical context: 'This will send a message to a real person.' It also explains the draft is sent to the original conversation and that optional text editing is possible. This goes beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise and well-structured. It uses bullet points for example user phrases and a clear warning. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description fully explains the tool's effect: approval, sending, optional editing, and the real-person warning. It covers all necessary context for an agent to use it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters (draft_id, edited_text) are described. The description adds context that edited_text is optional and used for modifications before sending, which is helpful but not essential. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Approve a pending agent draft and send the message.' It is specific about the action (approve and send) and the resource (agent draft), distinguishing it from siblings like agents_reject_draft.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit example phrases like 'Approve this draft', 'Send this reply', etc., guiding when to use the tool. It also notes that it sends to a real person, implying caution. It lacks explicit when-not-to-use cases, but the examples are sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds extensive behavioral detail beyond annotations: explains return format (status, response_text, messages[], full_reply, etc.), special status='silent' condition, field contents, and execution time. No contradictions with annotations (readOnlyHint: false aligns with mutation).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and efficient: first sentence states purpose, second gives usage, then detailed return info. Every sentence serves a purpose with no fluff. Front-loaded with key info.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description fully compensates by detailing the return structure, including edge cases (silent status, attachment-only sends). It covers execution time, model usage, and field semantics, making the tool behavior completely understandable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for all parameters. The description adds value by explaining send_mode default behavior and its non-effect on execution_mode. This nuance is helpful beyond the schema's basic descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action: 'Send a message to an AI agent and get its response.' It specifies the resource (agent), verb (send), and context (configured prompt, tools, knowledge). This distinguishes it from siblings like agents_create or agents_list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes explicit usage guidance: 'Use this to test agents or have them process a task.' While it doesn't list alternatives or when not to use, the context is clear enough to decide. No exclusions provided, but adequate for most use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate a non-read-only, non-destructive operation, which aligns with creation. The description adds context about execution modes and their behaviors, but doesn't disclose potential failure modes (e.g., duplicate names) or required permissions. However, it does not contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the main purpose and well-organized into execution modes. However, the 'Execution modes' section could be slightly more concise, as it repeats some information already in the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description does not specify return values, which is a minor gap. It covers the core functionality and execution modes thoroughly. For a creation tool with many siblings, it provides sufficient context for correct selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage, so baseline is 3. The description adds value by explaining defaults (OMIT for send_mode and text_engine) and detailing the text_engine enum options beyond the schema. However, it does not elaborate on other parameters like name constraints or prompt_id usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action 'Create a new AI agent in the workspace' and differentiates it from siblings like agents_update or agents_delete by focusing solely on creation. The specific verb+resource pair is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use each execution mode (ai_assisted, agentic, rule_based) with concrete 'Best for' examples. It also directs users to agents.update for setting keywords, clarifying boundaries between tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description claims permanent deletion and irreversibility, but annotations set destructiveHint=false, contradicting the described behavior. This is a serious inconsistency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two front-loaded sentences with no wasted words: purpose stated first, warning second.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequate for a simple deletion tool: warns about permanence and trigger removal. Lacks details on prerequisites but sufficient given low complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single parameter agent_id, so the description adds no additional meaning. Baseline score applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the action 'permanently delete' and the resource 'AI agent'. Distinguishes from siblings like agents_create and agents_update.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a warning about irreversibility but no explicit guidance on when to use versus alternatives like agents_update or agents_list. Implies usage for deletion but no exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds value by detailing the returned configuration fields, surpassing what annotations alone provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, front-loaded with the main purpose, and uses a clear bullet list for return details. Every sentence adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple 'get' tool with one required parameter and no output schema, the description is fairly complete. It details return fields but lacks mention of error handling (e.g., agent not found) or response format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter (agent_id) with schema description 'ID of the AI agent to fetch'. Schema coverage is 100%, so baseline 3 is appropriate. The description does not add extra context like format, examples, or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Get detailed information about a specific AI agent' and lists specific configuration sections returned, distinguishing it from sibling tools like agents_list (which lists all agents) and agents_create/agents_update.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly state when to use this tool vs alternatives (e.g., agents_list for a summary, agents_get for full details) nor provides prerequisites or exclusions. Usage is implied but not guided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations (readOnlyHint, idempotentHint, destructiveHint) already indicate safety. The description adds that this is the ONLY correct way to stay silent, explaining behavioral implications of alternatives beyond structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences that efficiently convey purpose, use cases, and a warning. No extraneous text; front-loaded with core function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one param, no output schema), the description covers all necessary aspects: purpose, when to use, behavioral uniqueness, and parameter detail. Fully adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single 'reason' parameter. The description adds value by explaining it's for admin audit, storage location, and filter limitations, enhancing the schema's meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool stops the turn without sending a message, and lists specific scenarios (human operator after job.escalate, guest self-resolving, duplicate, observation-only). It contrasts with narrated silence text which would be delivered verbatim, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit use cases and warns against using narrated silence text. While it doesn't directly compare to sibling tools like agent_handoff or agents_ask, the guidance is sufficient for appropriate use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by detailing the returned data (basic info, trigger count, knowledge collection count) and the role of the description field for routing, which goes beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized into a clear opening, details about return fields, guidance for router agents, and bulleted use cases. It is efficient with no unnecessary words, though slightly longer than strictly needed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple listing tool with no output schema, the description adequately explains what is returned (basic info, counts, descriptions) and the only parameter. It provides sufficient context for an agent to use the tool correctly, especially for discovering and selecting agents.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description covers the status parameter completely (enum values and explanation). The tool description reinforces the filtering use case but does not add new semantic information beyond what is in the schema. With 100% schema coverage, baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List all AI agents configured in the workspace' with a specific verb and resource. It also lists the return fields (basic info, trigger count, knowledge collection count). However, it does not explicitly differentiate from sibling listing tools like agents_list_drafts, but the purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides use cases: see all agents, filter by status, get IDs. It also advises router agents on how to use agent descriptions for delegation. However, it does not explicitly state when not to use this tool or contrast it with alternatives like agents_get or agents_list_drafts.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by disclosing that drafts are 'awaiting approval' and what each draft includes (thread info, trigger message, generated response, creation time, expiration). No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: starts with the core purpose, lists included details, and ends with example queries. Every sentence serves a purpose, no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only listing tool with two optional parameters and no output schema, the description adequately explains what the tool returns and when to use it. It could mention expiration details but is otherwise complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description does not add extra meaning beyond the schema's parameter descriptions, which are already clear for 'limit' and 'thread_id'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'List pending agent drafts awaiting approval.' It specifies the resource (drafts) and action (list), and distinguishes from sibling tools like agents_approve_draft and agents_reject_draft by focusing on the listing aspect.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit user queries that indicate when to use this tool, such as 'Show pending agent drafts' and 'List drafts to approve'. While it doesn't explicitly state when not to use it, the examples give clear context for usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only and non-destructive behavior. Description adds valuable context about chunk_count behavior (0 means still processing), which goes beyond annotations. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Highly concise: two sentences plus a note on chunk_count and references to sibling tools. Front-loaded with purpose, no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (1 required param, no output schema, annotations present), the description covers purpose, usage, and behavioral nuance completely. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single parameter 'agent_id'. The description does not add extra meaning beyond what the schema provides. Baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb and resource: 'List files directly attached to this agent'. Distinguishes from sibling tools like collections_list_files by specifying 'not shared collections'. Also mentions return fields.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use (list attached files) and references alternative tools: agents.add_file for attaching and agents.remove_file for detaching. Provides context on interpreting chunk_count for processing status.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the table is append-only and that every edit is snapshotted, which is useful. However, it does not describe pagination or the return format, which are behavioral aspects beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no fluff. First sentence defines the action and resource, second sentence provides usage guidance. Front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description lacks details about the return structure (fields like version_number, timestamp, prompt_text). Since there is no output schema, the description should compensate. However, the description implies a list of versions, and the workflow with `agents_prompt_restore` suggests the agent can infer the version number. This leaves gaps for a complete understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for all three parameters. The description does not add additional meaning beyond what the schema provides. Baseline of 3 is appropriate given high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it lists past versions of an agent's prompt_text (verb+resource+scope). It mentions the append-only table and the purpose of browsing history. However, it does not explicitly differentiate from the sibling tool `prompts_prompt_history`, which may serve a similar role for prompts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly guides the agent to use this tool to browse history, find a prior known-good version, and copy it into `agents.prompt_restore`. This provides a clear workflow, but does not mention when not to use or alternatives like `prompts_prompt_history`.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that the tool creates a new version and preserves history, which is consistent with annotations (readOnlyHint=false indicating mutation, destructiveHint=false). Adds context beyond annotations about the versioning mechanism.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loading the core action and key behavioral trait (history preserved), then providing usage guidance. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description adequately explains the effect (creates a new version). It references the prerequisite tool. Missing minor details like error handling, but overall complete for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for all three parameters. The description adds value by specifying that version_number comes from agents.prompt_history and that reason appears in history UI, enhancing understanding beyond the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool restores a past version of an agent's prompt_text by version_number, creating a new version while preserving history. It distinguishes itself from sibling tools like agents_prompt_history (which lists versions) and prompts_prompt_restore (for prompts vs agents).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs to use agents.prompt_history first to find the version_number, providing clear context for when to use this tool. It could be more explicit about when not to use, but the guidance is strong.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description explains the effect: 'The draft will be marked as rejected and won't be sent.' This adds behavioral context beyond the annotations (which don't indicate destructive behavior). There is no contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with only five short sentences, each serving a purpose. No wasted words, and the most important information (action, effect, usage triggers) is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool (2 parameters, no output schema), the description fully explains what the tool does, when to use it, and what happens to the draft. It is complete for the agent's decision-making.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters. The description adds minor context for 'reason' ('for logging/feedback'), but does not significantly enhance understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action: 'Reject a pending agent draft without sending.' It specifies the resource (agent draft) and the action (reject), and distinguishes it from siblings like agents_approve_draft.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use scenarios with example user phrases like 'Reject this draft', 'Don't send this', etc., and states the condition 'when the generated response isn't appropriate.' This offers clear guidance for an agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate non-read-only and non-destructive. The description adds valuable context that the file is not deleted but detached, which is not obvious from the annotations alone. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise: two essential sentences plus a practical tip. All information is front-loaded and no word is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with two required parameters and no output schema, the description covers the purpose, effect, parameter source, and non-destructive nature. It is complete and leaves no ambiguity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% coverage for both parameters. The description adds extra value by explaining how to obtain the file_id (via agents.list_files), which aids in correct parameter selection beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action: 'Remove a file from this agent's private knowledge.' It specifies the verb (remove) and the resource (file from agent), and distinguishes from siblings like agents_delete and agents_add_file.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear guidance: the file is only detached, not deleted, and directs to use agents.list_files to get the file_id. This helps the agent understand prerequisites and the non-destructive nature, though it does not explicitly state when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description aligns with annotations (readOnlyHint, destructiveHint, idempotentHint). Discloses default draft mode prevents real sends, and warns auto mode is only for test accounts. Explains overwrite behavior of drafts. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with clear sections for purpose, usage, and return format. Slightly verbose but every sentence adds value. Could be more concise but effective.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers all important aspects: core functionality, use cases, parameter details, return structure for both hit and miss, edge cases like blockchain and system messages. No output schema, but description provides comprehensive return format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Adds significant value beyond schema: explains send_mode's effects, system_message shape and purpose, blockchain_tx_data expected keys, attachment_file_ids usage. Each parameter's semantics are enriched.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool replays an inbound message through the trigger pipeline to check routing, using specific verbs and resources. It distinguishes from siblings like agents_ask by focusing on simulation rather than direct interaction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit use cases: verifying routing, determining matched agent/trigger, skip reasons. Advises using 'auto' only on test accounts. Could be improved by explicitly stating when not to use (e.g., for actual messaging).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=false and destructiveHint=false. The description adds that this tool reports task completion, implying a state change. However, it does not detail side effects (e.g., what happens if called multiple times) or other behavioral nuances beyond what annotations already convey. The description is adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loading the purpose and usage condition. Every word serves a function with no redundancy. It is appropriately concise for the tool's simplicity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (3 parameters, no output schema, no nested objects), the description covers the essential points: what it does and when to use it. It does not explain the return value or error handling, but for a reporting tool this is likely sufficient. Slightly more detail on prerequisites or effects could improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptive parameter names and descriptions. The description adds minimal parameter context by mentioning 'agent_task from DialogBrain' which relates to trace_id, but does not elaborate on success or summary beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Report') and resource ('that a Claude Code agent task has been completed'), clearly distinguishing this tool from sibling tools like agents_create or agents_ask. It also specifies the triggering context ('finish processing an agent_task from DialogBrain'), leaving no ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to call the tool: 'when you finish processing an agent_task from DialogBrain.' This provides clear usage context. Although it does not explicitly list alternatives or when not to use, the condition is specific enough to guide the agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations (readOnly, idempotent), the description reveals default stripping of LLM bodies, audit logging when including them, truncation behavior, and a 8KB cap on completion_text, which is critical behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: one clear sentence on purpose, followed by usage guidance and parameter behavior. No redundant information, every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 4 parameters, no output schema, and solid annotations, the description covers return details, default behaviors, edge cases (stripped bodies, audit, truncation, capped text), and practical use cases. Fully adequate for agent invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds explanations for each parameter: `full` as an escape hatch, `include_llm_bodies` as audited, `trace_id` from traces_list, `agent_id` for validation. This adds meaningful context beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches full execution detail for a single trace, listing specific components (tool executions, events timeline, LLM call spans) and distinguishes from the sibling tool `agents.traces_list` which lists traces.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly recommends use after `agents.traces_list` to drill into specific traces, providing context (failed run, slow run, unexpected outcome). Does not explicitly exclude alternatives but the guidance is clear and actionable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true and destructiveHint=false. The description adds behavioral context beyond this: it explains the agent_id predicate dropping rows, the `returned_count` vs `dropped_on_page` fields, and the edge case of all rows being dropped. It also mentions a known upstream bug for source filtering, which is valuable for the agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized into clear sections (purpose, usage, filters, response) but is somewhat lengthy. Every sentence adds information, but it could be tightened slightly without loss.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 8 parameters, no output schema, and complex filtering, the description covers purpose, usage, filter semantics, pagination, return fields, and an edge case. It is fully adequate for an agent to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining response fields (returned_count, dropped_on_page, has_more) and the edge case for pagination, which the schema does not cover. However, most parameter semantics are already in the schema, so the increase is modest.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List recent execution traces for an agent' and distinguishes it from sibling tools like `agents_trace_get` (for full detail) and `agents_traces_stats`. It also references the same data as /admin/requests, providing a clear verb-resource-scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit use cases ('when an agent call timed out, drafted the wrong response, or you want to know which tool/LLM call burned the latency') and recommends pairing with `agents.trace_get` for full detail. It also lists filters and pagination, making when-to-use clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds significant behavioral context: the exact-match scoping, days cap due to TTL, and the aggregated nature of the stats (not per-trace). No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with key purpose and metrics, no unnecessary words. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a stats aggregation tool with two parameters and no output schema, the description completely covers the output (list of metrics), usage context (bird's-eye view), constraints (exact match, days cap), and relationship to siblings. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides complete descriptions for both parameters (days with min/max/default, agent_id with workspace ownership). The description adds context about the days cap and scoping but does not add new semantics beyond what the schema provides. Baseline 3 is appropriate given 100% schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Get... trace statistics') and resource ('one agent'), clearly lists the metrics (total runs, success rate, etc.), and distinguishes from siblings by stating it's an aggregated bird's-eye view before diving into individual traces with agents.traces_list / agents.trace_get.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly tells when to use ('when you want a bird's-eye view of an agent's health before diving into individual traces'), mentions the scope (exact agent match, no substring bleed), and states the days cap (30) tied to TTL. Provides clear context on when to use vs alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide minimal info (readOnlyHint=false, destructiveHint=false). The description adds context about trigger types and conditions, which informs behavior, but does not disclose creation side effects, auth needs, or rate limits. With sparse annotations, description partially compensates.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with a clear purpose but becomes verbose with a long conditions section. It is structured with bullet points and sections, but could be more concise overall.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (7 parameters, nested objects, multiple trigger types), the description is comprehensive. It covers all trigger types and their conditions fields. No output schema exists, so return values are not required, but the description is complete for configuration.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds significant meaning beyond the schema for the 'conditions' parameter, detailing supported fields for each trigger type. This compensates for the complexity, raising the score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Create a new trigger for an AI agent' and explains what triggers are. It lists trigger types with brief explanations, distinguishing it from siblings like agents_trigger_update and agents_trigger_delete.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly state when to use this tool versus alternatives. It implies usage through the list of trigger types and conditions, but lacks explicit guidance on choice or when-not-to-use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds a warning 'cannot be undone' which contradicts the destructiveHint=false annotation (Annotation Contradiction). Despite adding behavioral context, the contradiction undermines transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no wasted words. The warning is important and front-loaded effectively.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, and description does not explain return values or confirmation. Missing context about what happens after deletion. Could mention related tools like agents_trigger_update.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description does not add extra meaning beyond the schema; it only names the tool and provides a warning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Delete a trigger from an AI agent' using a specific verb and resource. It distinguishes from sibling tools like agents_trigger_create and agents_trigger_update.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. Lacks context such as prerequisites or when to avoid deletion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations are minimal (readOnlyHint, destructiveHint both false), so the description adds value by clarifying 'only provided fields will be updated', indicating a non-destructive, partial update behavior. However, it does not disclose potential side effects, permissions, or behavior of omitted fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two sentences with no redundant information. The first sentence clearly identifies the action, and the second provides key behavioral context. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite the tool's complexity (8 parameters, nested objects, no output schema), the description is minimal. It does not explain the return value, error handling, or implications of updating conditions. Leaves significant gaps for an agent to understand the full behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds the insight that only provided fields are updated, but incorrectly claims 'all parameters are optional' when trigger_id and agent_id are required in the schema. This misrepresentation reduces the score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it updates an existing AI agent trigger. The verb 'Update' and resource 'AI agent trigger' are specific. It implicitly distinguishes from sibling tools like agents_trigger_create and agents_trigger_delete, but does not explicitly contrast them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives (e.g., create or delete). The note 'all parameters are optional' hints at partial updates but does not clarify prerequisites or exclusions. Missing explicit when-to-use or when-not-to-use context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide readOnlyHint=false and destructiveHint=false, which the description does not contradict. However, the description does not disclose that some parameters (e.g., prompt_text) are destructive. The burden is partially on parameter schema, but the main description could be more transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the main purpose, but the lengthy bullet list (19 items) could be trimmed. While informative, it is not maximally concise given the high parameter count.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers many use cases but lacks information on return values (no output schema) and error conditions. Additional context would be beneficial for a tool with 46 parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The bullet list in the description summarizes some parameters but does not add significant meaning beyond the detailed schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Update an existing AI agent's configuration.' It lists specific use cases (e.g., enable/disable, change name, assign prompt), making the tool's purpose obvious and distinct from siblings like agents_create and agents_delete.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'Use this to:' bullet list provides explicit guidance on when to use the tool. However, it does not explicitly contrast with siblings (e.g., when NOT to use it), which would improve decision-making.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses key behavioral traits beyond annotations: it overwrites prompt_text (with recoverability via history), does not change tool/model/execution settings, and only works for forked agents. This adds significant context that the annotations (only readOnlyHint and destructiveHint) do not cover. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured, with a clear first sentence stating the core action, followed by detailed usage guidelines and behavioral notes. Every sentence adds value, and there is no redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema) and adequate annotations, the description fully covers the necessary context: what changes, what does not, conditions for use, and recovery. It leaves no ambiguity for an AI agent to misapply the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already describes agent_id thoroughly ('ID of the forked agent to update from its template'), so schema coverage is 100%. The description adds the contextual constraint that the agent must be forked from a template, but this is implied in the parameter description. Thus, the description adds minimal additional meaning over the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the verb ('update') and resource ('forked agent's instructions') and distinguishes it from sibling tools like agents_update by specifying it updates from the originating template. It explicitly states the action: 'Update a forked agent's instructions (prompt) to the latest version of the system template it was created from.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use ('Use when the platform has improved a template...') and includes exclusions ('Only works on agents forked from a template (not from-scratch agents or templates themselves)'). It also provides clear context about what is overwritten and what is preserved.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes beyond annotations by explaining that the filter uses Voyage AI embeddings, how the description becomes a reference vector, and the threshold's effect on sensitivity. Annotations only state readOnlyHint=false and destructiveHint=false, so the description adds valuable behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: it starts with the core purpose, explains the mechanism, gives practical examples, and ends with a note on the embedding API call. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the tool's behavior thoroughly but omits mention of the return value after creation. Since there is no output schema, the agent is left uncertain about what the response includes (e.g., created filter ID). Otherwise, it is complete for a creation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides high-coverage descriptions (100%), but the description adds extra guidance: emphasizing the description field's importance, providing example phrasing, and elaborating on threshold sensitivity. This adds meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Create a new AI filter for semantic intent-based message matching.' It uses a specific verb (Create) and resource (AI filter), and the context distinguishes it from sibling tools like ai_filters_delete and ai_filters_list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on how the filter works (vector embeddings, cosine similarity) and explains the threshold usage, but does not explicitly mention when to use this tool versus alternatives like updating or testing filters. The logic is implied given the distinct 'create' action.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare destructiveHint=true, which the description reinforces by stating 'Permanently delete' and 'This action cannot be undone.' It adds valuable context about triggers referencing the filter, going beyond the bare annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, with the purpose in the first sentence, followed by a usage bullet and two sentences on consequences. Every sentence adds value, and the structure is front-loaded and well-organized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple delete tool with one parameter and comprehensive annotations, the description fully covers the key aspects: purpose, usage guidance, irreversibility, and impact on triggers. No gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage for the single parameter (filter_id). The description does not add any additional meaning beyond the schema's description, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Permanently delete an AI filter,' which clearly identifies the verb (delete) and resource (AI filter). The tool name and sibling tools like ai_filters_create and ai_filters_update distinguish it effectively.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes a 'When to use' bullet that specifies the user wants to remove a filter, providing clear context. It also warns about irreversibility and impact on triggers, though it does not explicitly mention when not to use or compare with siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds significant detail: it explains the semantic filtering mechanism (embeddings, cosine similarity), what fields are returned (id, name, description, threshold, is_active), and the overall behavior. There is no contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is somewhat lengthy but well-structured: it starts with the main purpose, then explains the underlying technology, followed by usage guidance and return fields. Every sentence serves a purpose, though it could be slightly more concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters, no output schema, and adequate annotations, the description comprehensively explains what the tool does, how it works, when to use it, and what it returns. It fully satisfies the context needed for a list tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero parameters, so schema coverage is 100%. The description does not need to elaborate on parameters. With no parameters, the baseline is 4, and the description adds no unnecessary param info, maintaining the score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List all AI filters for the current workspace' and explains the concept of AI filters, distinguishing it from sibling tools like ai_filters_create, ai_filters_delete, etc. It uses specific verbs and a defined resource, achieving high clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes a 'When to use' section with three specific use cases (check existing filters, get IDs for triggers, review thresholds/status), providing clear context. However, it does not explicitly state when not to use this tool or mention alternatives, which keeps it from a perfect score.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint, but the description adds crucial behavioral details: it calls the Voyage AI embedding API, computes cosine similarity, and returns similarity score, match boolean, and threshold. This goes beyond annotations by disclosing external dependency and computational steps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: a clear lead sentence, technical explanation, bulleted use cases, return format, and an important note about the external API call. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description fully explains the return value (similarity, matched, threshold) and the threshold logic. It also covers practical use cases and external API implications, making it complete for an agent to understand the tool's behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage, both parameters are already well-described in the input schema. The description does not add new semantic information about the parameters beyond what the schema provides, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Test a message against an AI filter to check whether it would match.' This distinct verb+resource combination differentiates it from sibling tools like ai_filters_create and ai_filters_list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit use cases: 'Verify a filter works as intended before using it in a trigger', 'Tune the threshold', and 'Debug why a message did or did not match a filter'. This guides the agent on when to apply this tool over its siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses a key behavioral trait: changing the description triggers a Voyage AI embedding API call to re-generate the reference vector. Annotations (readOnlyHint=false, destructiveHint=false) do not contradict. This adds value beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, then organized into clear sections for usage and side effects. Every sentence adds value; no redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description covers the update operation, partial updates, and side effects. It could mention what is returned (e.g., the updated filter), but overall it is sufficiently complete for an update tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds meaning: for threshold, explains 'higher = stricter matching'; for is_active, clarifies 'OMIT to leave unchanged'; for description, mentions the side effect. This enhances understanding beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Update an existing AI filter's name, description, threshold, or active state,' specifying the resource (AI filter) and action (update). Siblings include create, delete, list, test—so it is well-differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

A 'When to use' section lists four concrete scenarios (rename, refine description, adjust threshold, enable/disable). It does not explicitly state when not to use or suggest alternatives like deleting a filter, but the guidance is clear and context-rich.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, which are consistent with a mutation tool. The description adds valuable behavioral detail: 'If a tag is already applied it will be updated to is_manual=true.' No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is exceptionally concise, with a single purpose sentence, two bullet-point usage guidelines, and two sentences for parameter and behavior. No redundant words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple mutation tool with no output schema, the description covers purpose, usage, parameters, and idempotency behavior. It does not elaborate on return values or auth, but these are not critical for correct invocation given the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with clear descriptions for both parameters. The description restates the parameter requirements ('Provide the thread_id (integer) and an array of tag_ids to apply') but does not add significant semantic value beyond the schema. Baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Apply' and the resource 'AI tags to a thread', with the parenthetical '(manually)' distinguishing from automatic tagging. It effectively differentiates from siblings like ai_tags_remove_from_thread and ai_tags_create.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit 'When to use:' bullets, covering the common scenarios of labeling or categorizing a conversation. It does not mention alternatives or when not to use, but the context is clear given the sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that tags run on every incoming message and provides limits (20 personal/50 team tags). Annotations indicate non-destructive write, so no contradiction. Adds context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then explanation, use cases, and tips. Slightly wordy but each paragraph adds value. Efficient overall.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Lacks mention of what is returned after creation (e.g., tag ID). No output schema, so this is a gap. However, covers inputs well with limits and usage tips.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but description adds valuable tips for the 'description' parameter (classifier prompt, examples) and explains its role. This goes beyond schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Create a new AI tag' and explains its function as an automatic message filter. It distinguishes from sibling ai_tags_* tools (e.g., add/delete) by focusing on creation of the classifier definition.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Includes a dedicated 'When to use' section with specific use cases (auto-classify incoming messages, reduce costs). Missing explicit when-not-to-use and alternatives like ai_filters_create, but the guidance is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark destructiveHint true. The description adds that all thread associations are removed automatically and threads are not deleted, providing useful behavioral context beyond the annotations. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, with three short sentences and a separate 'When to use' line. It is front-loaded with the primary action and efficiently covers key details without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter, destructive tool with annotations and full schema coverage, the description covers purpose, usage guidance, behavioral effects, and consequences. No missing elements are apparent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already covers 100% of parameters with the description 'ID of the tag to delete'. The tool description adds no additional meaning to parameter semantics beyond that.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Delete' and resource 'personal AI tag'. It distinguishes from sibling tool ai_tags_remove_from_thread by emphasizing that all thread associations are removed automatically and the tag is permanently deleted.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'When to use' section explicitly states the user wants to permanently remove a tag. It also advises that this action is irreversible and threads are not deleted. However, it does not explicitly mention when not to use or list alternative tools for partial operations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns tags with thread counts for non-archived, included threads only, and explains the underlying lightweight classifier mechanism. This provides useful context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a title line, explanatory paragraph, bullet points for usage, and final line about return value. It is concise, front-loaded, and every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters or output schema, the description fully covers the tool's purpose, usage, and return information (tags with thread counts). It is complete and self-contained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters (schema coverage 100% vacuously). The description does not need to add parameter info. It effectively explains the return value and usage, meeting the baseline for zero-parameter tools.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List all personal AI tags' with a specific verb and resource. It distinguishes from sibling tools like ai_tags_create, ai_tags_add_to_thread, etc., by explaining that it lists auto-classification filters.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes explicit 'When to use' bullet points: check before creating, get IDs for add/remove, see thread counts. This provides clear guidance on when to use this tool versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds no additional behavioral context beyond restating 'remove'. It does not disclose side effects or constraints beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short, front-loaded with the action, and bullet points for use cases. Every sentence is purposeful with no waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple removal tool with no output schema, the description combined with annotations provides sufficient context. It clearly states what it does and when to use it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and description does not add extra meaning beyond reiterating the need for both parameters. No format or constraint details beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'Remove a specific AI tag from a thread' with a clear verb and resource. The sibling tool 'ai_tags_add_to_thread' provides contrast, making the purpose distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'When to use' section provides two common scenarios (un-label, correct tag) and reminds to provide both IDs. It lacks explicit 'when not to use' or alternatives, but for a simple removal, this is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations (readOnlyHint=false, etc.) already indicate mutation. Description accurately describes update operation but adds no additional behavioral context like permissions or side effects. With annotations covering safety profile, description offers minimal extra transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four concise sentences: purpose, usage scenarios, instruction to provide changed fields, and requirement. No fluff, front-loaded with main action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, parameter requirements, and usage scenarios. Lacks explanation of return value or error conditions, but for a simple update tool with no output schema, it is mostly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with detailed parameter descriptions. The description adds critical constraint 'At least one field is required' (beyond required tag_id), which is not in schema. Also repeats 'OMIT' hints but schema already includes them, so moderate added value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (update) and resource (personal AI tag), listing specific attributes (name, description, icon, color, active state). It distinguishes from sibling tools like ai_tags_create or ai_tags_delete.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Includes a 'When to use' section with specific scenarios (rename, change icon/color/description, enable/disable). Provides guidance to provide only changed fields and states at least one field is required. Lacks explicit when-not-to-use but is clear from context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context about identity switching via cookies/storage, consistent with annotations, but doesn't detail potential side effects beyond loading state.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no unnecessary words, efficiently conveying the core information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 required string params, no output schema) and supportive annotations, the description is mostly complete. However, it could mention prerequisites like the page being open or identity existence.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%. The description does not elaborate on the meaning or format of page_id or identity_name beyond what the parameter names imply, failing to compensate for the missing schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Switch the page's identity') and mechanism ('loading saved cookies + storage'), and effectively distinguishes it from the sibling tool browser.open.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use ('switching identity mid-page') and when not to ('for first navigation, pass identity_name to browser.open instead'), providing a direct alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide safety info (readOnlyHint, idempotentHint, destructiveHint). The description adds context about ref formats but no further behavioral details (e.g., click effects, page interaction). No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with front-loaded action. No unnecessary words. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple click tool, the description is largely complete. It lacks explanation of return values and page_id, but the action is clear and the ref guidance helps. Adequate for agent invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description explains 'ref' (aria-ref or CSS selector). It does not explain 'page_id', which is a required parameter. Partial coverage raises it slightly above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Click an element' with a specific verb and resource. It distinguishes from sibling browser tools like browser_fill, browser_type, etc., by specifying the click action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description advises 'Prefer the aria-ref token,' providing guidance on ref selection. However, it does not explicitly state when not to use or compare with alternatives like browser_hover or browser_drag.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description says 'Close' (write action) but annotation readOnlyHint=true contradicts this. No disclosure of side effects or idempotency despite annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with no wasted words; perfectly concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Simple tool with one param, but no output schema or return value description. Adequate for a close action but incomplete given the annotation contradiction.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema coverage, description should clarify page_id format or usage. It only says 'page opened by browser.open', adding minimal value over the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses specific verb 'Close' and resource 'page opened by browser.open', clearly distinguishing from siblings like browser_open and browser_tabs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied through pairing with browser.open, but no explicit when/when-not guidance or alternative tools are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds significant behavioral context beyond annotations: buffer cap of 500 entries, oldest dropped first, drainage behavior. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three efficient sentences, front-loaded with main purpose, no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers main behavior, filtering, buffer limit, and drain/peek behavior. Missing details about return value format and role of page_id, but acceptable for a simple retrieval tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Explains level, pattern, and clear parameters well, but fails to mention the required page_id parameter. Schema coverage is 0%, so description partially compensates but misses a key parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool returns console.log/warn/error events, with filtering by level and pattern. It distinguishes from sibling browser tools by focusing on console messages.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context for usage (since last drain, buffer caps, clear parameter for peeking) but does not explicitly compare to alternatives or state when not to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate the tool is read-only and idempotent. The description adds behavioral context by stating it performs a drag operation using CSS selectors and lists use cases. It does not contradict annotations. However, it could have disclosed more about potential page events triggered, but it is sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with three focused sentences: action definition, parameter explanation, and use cases. Every sentence adds value with no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and good annotations, the description covers the action, parameter semantics, and use cases. It does not explain return values or error conditions, which might be assumed, but overall it provides sufficient context for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description explains the meaning of source_ref (element to grab) and target_ref (drop target) and specifies they are CSS selectors, adding value beyond the schema which has no descriptions. However, the required page_id parameter is not explained, leaving a small gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb (drag) and resource (elements on a page), explains the parameters, and gives specific use cases (slider captchas, kanban, drag-and-drop uploads). This distinguishes it from sibling tools like browser_click or browser_hover.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description lists three use cases which imply when to use the tool, but it does not explicitly state when not to use it or suggest alternative tools for similar actions. Thus, it provides clear context but no exclusions or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds beyond that: result serialization details, 256KB output cap, and requirement to inline runtime values. This gives the agent a clear understanding of limitations and behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is four sentences, front-loaded with the core purpose. Every sentence adds unique value: use cases, expression format, output behavior, and size limit. No extraneous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description covers output format and size limit. It explains when to use the tool and expression syntax. Missing is mention of error handling (e.g., syntax errors) but that is a minor gap for a simple eval tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds meaning for 'expression' (plain JS value or IIFE, inline values) but doesn't elaborate on 'page_id'. With only two parameters, the description partially compensates but not fully.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool runs JavaScript in the page context and returns the result. It lists specific use cases (state not in a11y tree, captcha iframe inspection, DOM events) that distinguish it from sibling browser tools like browser_snapshot or browser_fill.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes when to use it ('Use for state not in the a11y tree...') and provides guidance on expression format and inlining values. It could be more explicit about when not to use it, but the context is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by disclosing the 25MB cap per file and the /tmp side effect for data blobs. However, it lacks details on error handling or prerequisites (e.g., the page must have a file input). No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two sentences with zero wasted words. It is front-loaded with the purpose and immediately gives usage details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description adequately covers the core functionality and constraints. However, it lacks explanation of what happens after the file is attached (e.g., success indication, no output schema), and the required parameters ref and page_id are not explained, leaving gaps for the AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description compensates partially by explaining the two data parameters (local_paths and data) and their formats. However, it does not explain the required parameters ref and page_id, which are crucial for the tool's operation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Attach files to an <input type=file>.' This is a specific verb+resource, and it distinguishes itself from sibling browser tools like browser_click or browser_fill by focusing on file uploads to file input elements.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit guidance on how to invoke the tool: 'Pass either local_paths (absolute host paths) or data (list of {name, mime, base64} blobs written to /tmp).' It also mentions a 25MB cap. However, it does not explicitly state when NOT to use this tool or alternatives, but the context is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description contradicts the readOnlyHint annotation; filling an input is a write operation, not read-only. This is a serious inconsistency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no unnecessary information. Clear and to the point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the tool is simple, the description lacks explanation of return values or post-fill effects. The page_id parameter is not clarified. The annotation contradiction also reduces completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description explains the 'ref' parameter in detail (aria-ref vs CSS selector), but does not cover 'value' or 'page_id'. Schema description coverage is 0%, so description partially compensates.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fills an input/textarea with a value, and distinguishes between aria-ref tokens and CSS selectors. It is a specific verb+resource description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides guidance on preferring aria-ref tokens over CSS selectors, but does not explicitly state when to use this tool versus alternatives like browser_fill_form or browser_type.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description claims 'Fill' which is a write/modification operation, but the annotations set 'readOnlyHint' to true, indicating a non-modifying operation. This is a direct contradiction. Additionally, the description does not disclose other behavioral traits like triggering events or requiring page load. The annotation contradiction severely undermines transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two sentences that state purpose, explain the key parameter structure, and provide a benefit comparison. No extraneous words, front-loaded with the primary action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description covers the essential usage. It explains input format and performance benefit. However, it doesn't describe the return value or error behavior, but for a form filling tool this is acceptable. The annotation contradiction is a gap but not directly in the description's completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description adds meaning for the 'fields' parameter (CSS selector, value types) but does not explain the 'page_id' parameter. The explanation for 'fields' is useful, but the lack of coverage for 'page_id' keeps this at a moderate score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Fill', the resource 'multiple form fields', and the scope 'in one call'. It distinguishes from the sibling tool 'browser_fill' by emphasizing batching, so the agent knows exactly what this tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly contrasts with 'browser.fill repeatedly', implying use when multiple fields need filling. It also explains the structure of the 'fields' parameter. However, it does not mention when not to use it or prerequisites like the form being present.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context about queuing and return value but does not significantly expand behavioral disclosure. There is a possible contradiction between 'respond' (mutation) and readOnlyHint=true.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two front-loaded sentences with no wasted words. Efficiently covers purpose, parameter usage, and behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description mentions the return value. It explains the queuing mechanism and required parameters, making the tool self-contained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaning beyond the schema: accept=true for OK, false for Cancel; prompt_text for prompt() dialogs. This is crucial given 0% schema description coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly specifies the action: responding to a pending JS dialog (alert/confirm/prompt). It distinguishes itself from other browser tools by focusing on dialog handling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explains when to use the tool (when a dialog is pending) and mentions that dialogs are queued at page-open time, with return value indicating no waiting dialog. It does not explicitly say when not to use it or mention alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds behavioral context by stating it reveals tooltips and hover menus, which is useful beyond the annotation data. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no wasted words, action stated upfront. Highly concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple hover tool with two parameters and no output schema, the description covers the core purpose and effect. Missing explanation of 'page_id' is a minor gap, but overall adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description adds meaning to the 'ref' parameter (CSS selector) but does not explain 'page_id'. For a two-parameter tool, this is partial compensation. A higher score would require explanation of both parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool's action ('hover the mouse over an element') and its effect ('reveals tooltips + hover menus'), using specific verbs and resource. It distinguishes from sibling browser tools like browser_click or browser_drag.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied (for hovering to reveal tooltips/menus) but no explicit when-to-use or when-not-to-use guidance is provided. Among many sibling browser tools, there is no direction on when to prefer hover over click, wait, etc.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that the tool returns new URL and title, but does not mention side effects, authorization needs, or edge cases (e.g., no history). There is a contradiction: readOnlyHint=true suggests no state change, but 'navigate back' implies changing the current page, which may be considered a state modification. This inconsistency lowers transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise—one sentence that states purpose and return value. It is front-loaded and efficient. However, it could add a bit more detail (e.g., what happens when history is empty) without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple navigation tool, the description provides basic purpose and return info. However, it lacks explanation of the page_id parameter and does not cover edge cases like empty history or behavior when already at the first page. Given the availability of annotations for safety, it is barely adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter 'page_id' has no description in the schema (0% coverage). The description does not explain what page_id is, how to obtain it, or its role. With no additional meaning beyond the schema, the parameter semantics are severely lacking.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Navigate back in the page's history (browser back button).' It uses a specific verb ('Navigate') and resource ('page's history'), and distinguishes itself from sibling browser tools like browser_open or browser_click by explicitly mentioning navigation backward. Also specifies what it returns: new URL and title.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage (when you want to go back in history) but provides no explicit guidance on when to use vs alternatives, such as other navigation tools like browser_open or browser_click. No exclusions or context provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true and idempotentHint=true, so the description's contribution is the behavioral detail: it captures up to 200 most recent requests per page and resets on 'drain'. However, the 'clear' parameter is not explained, which could be important for controlling the drain behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, consisting of two short sentences. The first sentence clearly states the action, and the second lists key filters and limits. Every phrase serves a purpose, and no redundant information is present.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite the tool's moderate complexity (5 parameters, no output schema), the description omits critical details. It does not explain the output format of the requests, nor does it describe the clear parameter. A user would need to infer the behavior from the parameter names alone, which is insufficient for full understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description does little justice to the parameters. It mentions method, url_pattern, and status_min as optional filters, but does not explain the required page_id parameter or the clear parameter. The description adds minimal meaning beyond the parameter names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'List' and resource 'HTTP requests', making it clear this tool retrieves network activity. It distinguishes itself from sibling browser interaction tools (e.g., browser_click, browser_snapshot) by focusing on network data. The scope 'since open or last drain' adds precision.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide explicit guidance on when to use this tool versus alternatives. There are no sibling tools that also list network requests, but the lack of usage context (e.g., 'Use this when debugging page load issues') reduces clarity. No conditions or exclusions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint, idempotentHint, destructiveHint false. Description adds valuable context about cookie auto-attachment and identity override, enhancing transparency beyond structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences. First sentence states purpose, second adds behavioral detail. No unnecessary words, front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with no output schema, description covers key behavior. Could mention what happens on invalid URL or missing identity, but acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so description must compensate. It explains identity_name well (override auto-matching) but does not describe url format or constraints. Partial compensation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Open a URL in a remote browser' with a specific verb and resource. It is distinct from sibling browser tools like click, fill, etc., which are for other actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context about auto-attaching cookies and overriding identity. Implicitly tells when to use (open URL) but does not explicitly exclude alternatives or mention when not to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description says 'Press a keyboard key', which is a write action, but annotations declare readOnlyHint=true, a clear contradiction. The description does not disclose side effects (e.g., triggering events, navigation) and does not resolve the annotation inconsistency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the action, examples in parentheses, no redundant text. Every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema; description omits return value or behavioral effects (e.g., whether the press triggers navigation, submits forms). Given the simple action and available annotations, the description should clarify the actual impact, especially to resolve the readOnlyHint contradiction.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 0% description coverage; description explains 'key' with examples and 'ref' (aria-ref or CSS selector) but does not explain 'page_id', which is required. This partially compensates for missing schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool presses a keyboard key, with specific examples (Enter, Tab, Escape, ArrowDown) and indicates it can press single characters. This distinguishes it from sibling tools like browser_type (for typing strings) and browser_click (for clicking).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description implies use for key presses but does not explicitly guide when to use versus alternatives like browser_type or browser_click. It provides context (optional ref for focusing) but no exclusions or comparisons.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only and non-destructive behavior. Description adds valuable behavioral context about viewport changes affecting HTML rendering and anti-bot detection, which goes beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no redundancy. The key purpose and use cases are front-loaded, making it efficient for an AI agent to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple resize tool with no output schema and basic annotations, the description adequately covers purpose and context but misses parameter semantics. This is sufficient for a minimal viable description but has clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 0% coverage, but description does not explain any parameter details (e.g., units for width/height, that page_id refers to an open tab). It only implies that width and height are dimensions, leaving considerable ambiguity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Resize the page viewport' with specific verb and resource. It distinguishes from sibling browser tools by focusing solely on viewport sizing and providing concrete use cases like responsive design testing and anti-bot evasion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description gives explicit when-to-use scenarios (site serving different HTML, anti-bot scoring). While it doesn't explicitly state when not to use or list alternatives, the context is clear and no direct sibling competition exists for this specific action.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=true and destructiveHint=false. The description adds that it works on native <select> elements, which is a key behavioral constraint not covered by annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the purpose, and every sentence adds value. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no output schema and 0% schema coverage, the description covers some parameter usage but omits ref and page_id explanations and does not mention error conditions or the outcome of selection. Adequate but with gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description adds meaning for value and label parameters, explaining their use. However, required parameters ref and page_id are not explained, leaving gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'Pick option(s) in a native <select> dropdown,' which is a specific verb and resource. It distinguishes this tool from sibling tools like browser_click or browser_fill by focusing on select dropdowns.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains how to use parameters (value or label) and mentions lists for multi-select. However, it does not explicitly state when to use this tool versus alternatives or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context such as truncation at 32KB and the format of ref tokens, which is helpful beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, with no unnecessary words. It front-loads the purpose and then provides critical usage details in a well-structured manner.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the return format, ref token usage, and truncation limit. However, it lacks an explanation of the page_id parameter, which is a minor gap given that other sibling tools also use page_id and context may fill it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has one required parameter (page_id) with 0% description coverage. The description does not explain what page_id refers to or how to obtain it, leaving a gap in understanding. Since the parameter is not described, the agent may misuse the tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns a YAML aria_snapshot of the page DOM, tagging interactive nodes with `[ref=eN]` tokens. It distinguishes itself from sibling tools like browser_click and browser_fill by explaining how the ref tokens are used.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidelines: pass the eN token as the `ref` argument to other browser tools, and do NOT pass the role name. This helps the agent select and use the tool correctly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description lists actions including close and new, which are write operations that modify tab state, yet annotations declare readOnlyHint=true, creating a direct contradiction. No additional behavioral details such as side effects, permissions, or error conditions are disclosed beyond the annotation mismatch.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short (two sentences), front-loads the core purpose, and lists actions. However, it sacrifices completeness for brevity, especially regarding parameter roles. Still, it is efficient and easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema and enums, the description should provide more detail on return values for all actions and parameter behavior. It covers list and new returns but omits switch and close behavior. The overall description is adequate for basic use but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.