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

Goes well beyond the annotations by disclosing that the specialist 'runs synchronously' and that its response is 'already shown to the user in real-time,' plus the existence of `timeout`/`error` statuses and the expected post-call behavior. It adds no information on auth requirements, rate limits, recursion/depth limits, or what a failed delegation returns, which keeps it out of the top score.

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?

Purpose and trigger are front-loaded in the first two sentences, and the remaining sentences each address a distinct failure mode (past-tense summary, not saying 'I will delegate', error handling). Slightly dense with imperative post-call instructions, but no sentence 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 6-parameter, side-effect-bearing delegation tool with no output schema, the description covers the odd sync semantics, the fact that output is already user-visible, and error states — the highest-risk gaps. It omits guidance on choosing between agent_id and target_slug in description text, though the schema covers that.

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 every parameter (mode, payload, agent_id, target_slug, in_workspace, task_description) is already documented in the schema with more detail than the description offers. The description adds no parameter-level meaning beyond that, which is the expected baseline when the schema carries the full burden.

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?

States a specific verb and resource — 'Delegate a multi-step task ... to the full agentic planner' — with concrete examples (research, composing messages, booking, scheduling) and a clear scope ('more than a direct answer'). It does not, however, distinguish itself from closely related siblings such as calls_dispatch_agent, agents_ask, background_run, or job_escalate, leaving the agent to infer the boundary.

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?

Gives an explicit trigger condition ('Use when a user ask needs more than a direct answer') and rich guidance on what to do after the call, including how to phrase the result and how to handle `timeout`/`error` statuses. It stops short of naming when NOT to use it or which sibling (e.g. calls_dispatch_agent, agents_ask) to prefer instead.

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 readOnly/idempotent/non-destructive behavior, so the description focuses on useful extras: 30-day trace retention, a default 24h window, and the UTC interpretation of since/until — all genuinely beyond the structured fields. It omits explicit auth/error behavior, but retention and timezone semantics are real added 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?

Front-loaded with what it does, then parameters, then the timezone caveat — a sensible order. It is slightly padded (the 'compute them from the current date/time you were given' instruction recurs near the timezone note), but every sentence carries useful 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?

For a read tool with no output schema, it covers defaults, retention, timezone handling, and a sketch of the return shape (run counts, per-day, top tools), which is enough to call it correctly. The only uncovered item is in_workspace, and its session-scoping caveat is left to the schema.

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, but the description adds real meaning beyond the schema: ISO vs bare-date formats for since/until, how to compute them from the supplied current time, and that omitting `agent` means 'yourself'. It does not touch in_workspace or limit, so not a full 5.

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 gives a specific verb and resource — 'see what you or another agent actually did over a time window' — and enumerates the returned content (messages, documents, calls, plus a run-count/per-day/top-tools summary). It is unambiguous what the tool produces, but it never names or contrasts a sibling (e.g. agents_traces_list / agents_traces_stats), so an agent must infer the boundary from the returned payload.

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 explicit and framed around concrete questions ('what did I do today / yesterday / last week / in the last hour?' or 'what did <agent> do?'), which tells the agent exactly when to reach for it. There is no exclusion guidance or routing to overlapping trace tools, so it stops short of 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 declare it is a write (readOnlyHint=false), not destructive, and not idempotent, so the safety profile is covered. The description adds genuinely new behavioral context: indexing is asynchronous, the returned chunk_count reads 0 while processing, and final state must be checked later via agents.list_files. It omits failure modes such as re-attaching a duplicate file or a file that was never ingested.

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?

Purpose is front-loaded in one sentence, followed by a tight three-step numbered workflow and a single return-value caveat. Every sentence carries information; nothing is restated or padded.

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 correctly compensates by explaining the chunk_count return and its transient zero value, and the pipeline prerequisites are fully spelled out. It leaves minor gaps around duplicate attachments and permission requirements, but is otherwise sufficient 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 description coverage is 100%, so file_id, agent_id, and in_workspace are already documented in the schema, including that file_id comes from files_upload or files_ingest. The description reinforces the file_id provenance through its workflow but adds no new syntactic or semantic detail beyond the structured fields, so the baseline 3 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?

The first sentence gives a specific verb and resource ("Attach a file to this agent's private knowledge") and immediately scopes it against the sibling concept by clarifying these are agent-specific files "not shared with other agents." An agent can distinguish this from collections_add_file or a shared-knowledge tool without opening any schema.

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 numbered workflow explicitly sequences prerequisites (files_upload, then files_ingest, then this tool) and names the exact parameters to pass at each step, which is strong when-to-use guidance. It stops short of stating when NOT to use this tool (e.g. shared collections vs. agent-private knowledge), so it falls just short of 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 declare destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is covered structurally. The description adds genuinely new context: the message goes to the draft's originating conversation, edited_text can substitute, and it reaches a real person. It doesn't state irreversibility or any undo path, keeping it below a 5.

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-loads the core action and consequence in the first sentence, followed by the effect, then routing phrases, then the warning. The four trigger-phrase bullets are slightly repetitive but earn their place as routing cues. No filler beyond that.

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 mutation tool with no output schema, the description covers what is affected (the draft's conversation), the optional modification path, and the real-world consequence. With annotations supplying the destructive/non-idempotent profile, an agent has everything needed to call this 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 description coverage is 100%, so draft_id, edited_text and in_workspace are already documented in the schema. The description only alludes to the optional edit ('You can optionally edit the text before sending'), adding no syntax, format, or constraint detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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?

States a precise verb and resource ('Approve a pending agent draft') plus the consequential effect ('send the message'), so the agent knows exactly what the call does. It does not name the obvious alternative (agents_reject_draft) or any other sibling, so it falls short of full sibling differentiation.

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?

Gives concrete trigger phrases ('Approve this draft', 'Send this reply') that map user intent to this tool, which is strong positive routing guidance. It never states when NOT to use it (e.g., use agents_reject_draft if the user wants changes), so the exclusion side is missing.

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 only give the coarse safety profile (non-read-only, non-destructive, non-idempotent, closed-world). The description adds real behavioral context: execution takes 10-60s, background runs detach from the connection and survive up to 15 min, status='silent' is defined precisely, and it explains that a synchronous call is cancelled if the MCP request dies. This is well beyond what the annotations convey.

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?

Purpose is front-loaded in the first line, then return shape and execution semantics. It is dense and the return-value enumeration is long, but nearly every clause carries usable information (status semantics, full_reply vs messages distinction, attachment handling). Slightly verbose for a definition but 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?

With no output schema, the description carries the full burden of explaining returns and does so thoroughly (status values, messages[], full_reply, tool_calls[] trace, model/tokens). Combined with the background/synchronous tradeoff and attachment behavior, an agent has everything needed to call 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 description coverage is 100%, so the schema already documents all six parameters, and much of the description's parameter text (send_mode vs execution_mode, background, attachments) mirrors the schema. It adds marginal framing but does not materially extend meaning beyond the structured fields, so the baseline 3 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?

States a specific verb+resource: send a message to an AI agent and get its response, plus the scope that the agent runs with its own prompt/tools/knowledge. An agent can tell this apart from pure-read siblings like agents_get or agents_traces_list. It stops short of explicitly naming the sibling alternatives (e.g. agents_simulate_inbound, calls_dispatch_agent), so 4 rather than 5.

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?

Gives clear context: 'Use this to test agents or have them process a task.' It also gives conditional guidance for background=true (runs expected to exceed ~2 minutes) vs the synchronous default. It does not name when NOT to use it or point at specific alternative siblings, so it lands at 4.

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, idempotentHint=false, destructiveHint=false) already establish that this is a non-idempotent write, and the description usefully adds that `model` is applied post-creation (no follow-up update), that `allowed_tools` REPLACES the standard set, and that an empty list leaves no tools. Against that, it introduces a real ambiguity: the body calls `ai_assisted` the default mode while the schema declares `agentic` the default and omits `ai_assisted` from the enum entirely, muddying the core behavior of an omitted text_engine.

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-loads the purpose, then uses labeled bullets for modes and short paragraphs for tools/templates, which is well structured for a 12-parameter tool. It repeats a fair amount of schema text (model, template, allowed_tools) and the execution-mode list carries the misleading default claim, costing the top score.

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 should ideally say what creation returns (agent id/handle), which it omits. Otherwise it covers the complex boolean-like interactions (template suppressing name/text_engine/send_mode, tool-list semantics, engine modes) well enough for an agent to call it correctly, modulo the default-mode inconsistency.

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 baseline is 3; the description earns above that by adding semantics the schema lacks, notably the mutual exclusivity of `prompt_text`/`prompt_id` and the replacement (not additive) behavior of `allowed_tools`. It does not add much to `model`, `max_iterations`, or `in_workspace` beyond what the schema text already says.

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?

States a specific verb and resource ('Create a new AI agent in the workspace') and immediately distinguishes itself from siblings by covering execution modes, template instantiation, and tool assignment. An agent can tell it apart from agents_update, agents_update_from_template, and agents_trigger_create without opening the schema.

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?

Gives clear routing conditions: use `template` to also get the built-in trigger ('no need to add a trigger separately'), use `prompt_text` or `prompt_id` but not both, and reference to agents.update for keyword/reply-rule config. It does not, however, state when to prefer this over agents_update or agents_update_from_template for an existing agent, leaving one sibling choice to inference.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description adds genuinely new context beyond them: the operation is irreversible and cascades to delete all triggers, which the annotations do not convey. It stops short of mentioning auth requirements or effects on references.

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 tight sentences with zero filler. The permanence warning is front-loaded and the cascade consequence follows immediately, so the most decision-relevant information hits first.

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 destructive tool with no output schema and full annotation coverage, the description supplies the two facts that matter most: irreversibility and cascading trigger removal. It omits secondary concerns like workspace scoping behavior and permission requirements, keeping it just short of 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 both parameters (agent_id, in_workspace) are fully documented in the schema itself. The description adds no parameter-level detail, which is acceptable at full coverage but earns only the 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?

States a specific verb and resource ('Permanently delete an AI agent') and implicitly distinguishes itself from siblings like agents_trigger_delete and agents_update by noting the cascade to triggers. An agent can identify the operation without opening the schema.

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 prefer this over alternatives such as agents_update or agents_trigger_delete, and no prerequisites or required permissions stated. The warning implies caution but not selection criteria.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description goes beyond that by disclosing the shape of the payload — execution, tool, knowledge, escalation config, triggers, collections, prompt_text and auto_reply_rules — which materially helps an agent decide whether this call has the data it needs.

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 one-line purpose is front-loaded and the returned-config bullets are scannable. The list is somewhat long but each item names a distinct config area an agent would otherwise have to discover by calling the tool.

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?

There is no output schema, but the description compensates by enumerating the returned config sections, which is the main thing an agent needs to know before calling. Combined with complete annotation coverage and full parameter documentation, the definition is nearly self-sufficient; only error/not-found behavior is unaddressed.

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 both parameters, including the workspace-scoping semantics of in_workspace, so the schema carries the burden. The description adds no parameter-level detail (no format, no constraints on agent_id), making this a baseline 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?

States a specific verb and resource ('Get detailed information about a specific AI agent') and the bullet list pins down exactly which config sections are returned, so the agent knows this is a full-config fetch rather than a summary. It does not explicitly name siblings such as agents_list or agents_trace_get, so differentiation is inferred from 'a specific agent' rather than stated.

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?

There is no when-to-use or when-not-to-use guidance and no named alternative. The description never tells the agent to use agents_list for enumeration or agents_update for modification, nor does it state the prerequisite of having a valid agent_id.

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 readOnly/idempotent/non-destructive, and the description goes beyond them by disclosing the critical behavioral trap: narrated silence text ('*(Staying silent…)*', 'Internal:…') is delivered to the guest verbatim, so this tool is the only safe way to stay silent. It also notes the reason field is retained for admin audit.

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, tightly front-loaded: the action first, then use-cases, then the failure mode being warned against. Every sentence carries distinct, non-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?

For a no-op control tool with full schema coverage and a rich annotations block, the description supplies everything needed to call it correctly: what it does, when to invoke it, and why substituting text is harmful. No output schema is needed for a tool that by definition sends nothing.

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% and the schema already explains both parameters in detail (reason stored in trace_tool_executions.tool_params; in_workspace semantics). The description adds no parameter-level detail beyond what the schema provides, so the baseline of 3 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?

The description states a specific verb and effect ('End this turn without sending any message'), which is unambiguous and clearly distinct from siblings like messages_send or job_escalate. An agent can immediately tell this is the silence/no-op path, not an outbound-message tool.

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 enumerates explicit when-to-use conditions (thread owned by a human after job.escalate, guest self-resolving, duplicate message, observation-only turns) and names the wrong alternative (narrated silence text). Nothing is left to inference.

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 readOnly, idempotent, closed-world, and non-destructive, so the safety bar is satisfied. The description adds genuine behavioral value by disclosing the return shape (basic info, trigger count, knowledge collection count) and the semantic meaning of the per-agent description field, which the annotations cannot convey.

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-loads the core action and return summary, then uses a short bullet list for the enumerated uses. Slightly padded by the router/handoff paragraph, but every part is relevant and no sentence is filler.

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 carries the return-shape burden and does so (basic info plus trigger and knowledge counts). It is complete enough to call correctly; only minor gaps remain, such as pagination or result size 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 description coverage is 100%, so both parameters—including the status enum and the workspace override—are already fully documented in the schema. The description restates the status filter ('active/paused/archived') but adds no syntax or semantics beyond it, so the baseline of 3 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?

States a specific verb and resource ('List all AI agents configured in the workspace'), immediately distinguishing it from single-agent siblings like agents_get. An agent can tell what this returns without opening the schema.

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 when-to-use context: see all agents, filter by status, and retrieve agent IDs for further operations. It also frames the router/delegation scenario, but names no explicit exclusion or alternative sibling (e.g., 'use agents_get for a single agent'), so it stops short of a full 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: it discloses the contents of each draft returned (thread info, trigger message, response text, creation/expiration).

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 the core purpose, then a compact bulleted field list, then usage triggers. The bullet list is slightly longer than needed but each line earns its place by describing returned content.

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 compensates well by enumerating the returned fields and covering the read-only safety case via annotations. It is essentially complete for a zero-required-param list tool, with only minor gaps around pagination/result ordering.

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 read-only parameters (limit, thread_id, in_workspace) are already fully documented in the schema. The description adds no syntax or formatting detail for them, 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?

States a specific verb and resource ('List pending agent drafts awaiting approval') and adds a clarifying scope ('generated by AI agents but not yet sent'). This clearly separates it from sibling list tools like agents_list by specifying the pending-draft domain.

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 trigger phrasing ('Show pending agent drafts', 'What messages are waiting for approval?', 'List drafts to approve') that maps user intent to this tool. It does not name alternatives or exclusions (e.g., that approval itself belongs to agents_approve_draft), so it stops short of full when/when-not guidance.

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 real value beyond that: it enumerates the returned fields and explains that chunk_count=0 means the file is still processing, which is genuinely useful operational 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?

Three short sentences, front-loaded with the core purpose, followed by return semantics and a routing hint. No filler; every sentence 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?

No output schema exists, but the description compensates by listing the returned fields and their meaning. Combined with full schema coverage and annotations covering the safety profile, an agent has everything needed to call this 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 description coverage is 100%, so both agent_id and in_workspace are fully documented in the schema. The description adds no syntax, format, or constraint detail beyond what the schema already provides, so the baseline 3 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?

States a specific verb (List) and resource (files attached to this agent) with an explicit scope qualifier distinguishing it from shared collections. An agent can tell it apart from collections_list_files without opening either schema.

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?

Names the complementary tools agents.add_file and agents.remove_file for attaching/detaching, giving clear context. It does not, however, explicitly state when to prefer this over collections_list_files or search_files, so it falls short of full when/when-not guidance.

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 readOnly, idempotent, non-destructive, non-open-world, so safety needs no restating. The description adds the return shape (which fields come back per integration) plus the "enabled (or available)" nuance, which is useful since there is no output schema; it stops short of noting pagination or auth requirements.

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, zero filler, with the resource and its returned fields front-loaded and the routing hint second. Every clause 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?

With no output schema, the description usefully compensates by naming the fields returned, and the read-only nature is fully covered by annotations. It leaves the in_workspace parameter entirely to the schema and says nothing about result limits, so it is strong but not exhaustive.

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 agent_id and in_workspace are already documented, and in_workspace's non-persistent behavior is spelled out in the schema itself. The description adds no parameter syntax or format detail beyond the implicit scoping to a single agent, so the baseline 3 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?

The description gives a specific verb+resource ("List the workspace integrations enabled (or available) for an AI agent") and enumerates exactly what each entry contains (workspace_integration_id, provider, enabled flag, denied-tool count). It also names the sibling it complements (agents_set_integration), so an agent can distinguish it without opening either schema.

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 states the use case explicitly ("Use this to see what an agent can call") and points at the alternative action ("before toggling with agents_set_integration"), making the read-then-write pairing unambiguous. Nothing about when to reach for this vs. the setter is left to inference.

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond them: every prompt edit is snapshotted into an append-only table, implying complete and immutable history, which is useful for judging result reliability.

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 tight sentences: the first establishes what is listed, the second establishes why and what to do next. No filler, and the purpose 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?

For a read-only history listing with no output schema, the description is sufficient: it tells the agent what the records are, why the list is complete, and how the results are meant to be consumed (via agents.prompt_restore). Annotations cover the safety profile, and pagination parameters are fully described in the schema.

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 all four parameters (agent_id, limit, before_version cursor, in_workspace) are already documented in the schema. The description adds no extra syntax or semantics for them, so the baseline 3 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?

States a specific verb and resource ('List past versions of an agent's prompt_text') and adds the domain detail that these are append-only snapshots of every edit. It also distinguishes itself from the related restore path by naming `agents.prompt_restore` as the destination for a chosen version.

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 frames the use case: browse history to find a prior known-good version and then copy it into `agents.prompt_restore`, which effectively routes the agent between the two tools. It stops short of stating when *not* to use it (e.g., to fetch current prompt text, use agents_get), so it is clear but not exhaustive.

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=false and destructiveHint=false; the description adds the important non-obvious behavior that the restore appends a NEW version rather than overwriting, so history is preserved. This explains why a mutation is non-destructive, which the bare annotations cannot convey. It does not cover idempotency nuances (e.g. that repeating the call creates another version) despite idempotentHint=false.

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 short sentences, front-loaded with the action and the append-only consequence, then the prerequisite. No filler and no repetition.

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 mutation tool with no output schema and full annotation coverage, the description supplies the remaining essentials: what is being restored, the versioning semantics, and the prerequisite lookup tool. Nothing needed to call it correctly is missing.

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%, and the schema already documents each parameter including the note that version_number comes from agents.prompt_history. The description largely restates that, so it meets the baseline without adding syntax or constraint detail 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?

States a specific verb (restore) plus the exact resource and field targeted (`prompt_text`), keyed by version_number. It is clearly distinguishable from siblings such as agents_prompt_history, agents_update, and prompts_prompt_restore.

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 prescribes the prerequisite workflow: call `agents.prompt_history` first to obtain the version_number. That sequencing guidance is exactly what an agent needs to invoke this tool correctly rather than guessing a version number.

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 destructiveHint=false, readOnlyHint=false, and idempotentHint=false. The description adds useful context that the draft 'will be marked as rejected and won't be sent,' clarifying the state transition. However, it does not disclose whether rejection is reversible, whether a reason is logged (though schema hints at this), or any permission requirements.

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-loads the core action in the first sentence, followed by behavioral note and usage examples. The list of user phrasings is somewhat verbose but serves as helpful trigger recognition; overall efficient with no wasted sentences.

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 the essential action, effect, and when-to-use examples. Minor gaps exist: no mention of irreversibility or alternative tools, but for a simple state-change tool with full schema coverage and annotations, this is largely 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 all three parameters are already documented in the schema with descriptions. The description adds no new semantic details about parameters beyond what the schema provides, 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?

States a specific verb (reject) and resource (pending agent draft) with the key scope constraint 'without sending.' An agent can immediately distinguish this 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?

Provides clear when-to-use guidance with example user utterances ('Reject this draft', 'Don't send this'). However, it does not explicitly name the alternative (agents_approve_draft) or state when-not-to-use conditions such as rejecting an already-sent message.

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=false and readOnlyHint=false, which on its own is ambiguous for a removal operation. The description resolves that ambiguity by explaining the file is not deleted, only detached — genuinely additive context. It doesn't address idempotency (annotations say idempotentHint=false) or what happens when the file isn't attached, leaving a small gap.

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 short sentences, front-loaded with the action and the single most important caveat (non-destructive detach), then the prerequisite. No filler.

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 detach operation with full schema coverage, annotations, and no output schema, the description covers what is needed to call it correctly. Only minor behavior (error on a non-attached file, idempotency) is unaddressed.

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 all three parameters are already documented in the schema, including file_id's origin. The description reinforces the file_id source but adds no semantics beyond the schema, so the baseline 3 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?

States a specific verb and resource ('Remove a file from this agent's private knowledge') and immediately disambiguates scope by clarifying it is a detach rather than a delete. This distinguishes it from files_delete and agents.delete, which an agent could otherwise confuse it with.

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 points to agents.list_files as the way to obtain the file_id, which is a useful workflow hint, but never states when to prefer this over siblings like files_delete, collections_remove_file, or agents.add_file's inverse. Usage is implied rather than contrasted with 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?

The description claims "Idempotent upsert — safe to call repeatedly," but the annotations declare idempotentHint=false, a direct conflict on the tool's most safety-relevant property. The claim is also internally strained by the schema's own "on first enable" caveat, so an agent relying on it could misjudge whether re-calling changes write-tool exposure. This is an annotation 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?

Two short paragraphs, front-loaded with the purpose and effect, then the default-block behavior and the idempotency note. The only mildly redundant sentence is the integrations_list pointer, which also duplicates the schema, but nothing else is filler.

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?

It covers purpose, the sibling needed to obtain the required ID, the default WRITE-tool blocking, and the ephemerality of in_workspace (also in schema), which is good coverage for a config-mutating tool with no output schema. However, it omits any permission/authorization requirements for changing agent configuration and its idempotency claim is misleading, leaving an agent with a false model of repeat-call 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 description coverage is 100%, so every parameter including denied_tools and in_workspace is already documented in the schema. The description reinforces the non-obvious denied_tools default (auto-deny WRITE-class tools on enable) but adds no new syntax, format, or interaction detail beyond what the schema states, so the baseline 3 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?

The description names a specific verb and resource ("Enable or disable a connected workspace integration on an AI agent") and immediately scopes the effect to which ext<id>_<name> tools the agent and its sandboxed workbench runs may call. This clearly separates it from siblings like agents_list_integrations (which reads) and integrations_list (which resolves IDs), so an agent can route without opening either schema.

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 routes the agent to a specific sibling for prerequisite data ("Use integrations_list to get the workspace_integration_id") and spells out the when-to-use branches for denied_tools (omit for auto-deny of WRITE tools, [] to force-allow, list to block specific ones). What is missing is any explicit when-not-to-use guidance or a note about which sibling to call instead when the goal is merely inspecting the current integration state.

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 readOnly/idempotent/non-destructive, and the description adds real value on top: the draft-vs-auto distinction, the warning that drafts get overwritten, and that 'auto' is the only way to verify end-to-end delivery. It does not explicitly reconcile readOnlyHint=true with the fact that 'auto' mode actually sends a real message, leaving a minor tension an agent must infer.

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 and routing mechanics before the return shape. The inline enumeration of the full response object is long but earns its place given there is no output schema; slightly verbose for a prose description.

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 the routing model, the safe/unsafe delivery modes, the alternate blockchain event path, and both hit and miss response shapes — filling the gap left by the missing output schema. An agent has everything needed to invoke 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 description coverage is 100%, so the schema already documents all nine parameters in depth; the description only re-touches send_mode and blockchain_tx_data. Baseline 3 is appropriate since the schema, not the description, carries parameter 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?

States a specific verb and resource ('replay an inbound message on a thread through the real trigger pipeline') plus the outcome ('return what would have happened'). An agent can immediately tell this apart from observers like agents_trace_get or agents_activity, which report on past runs rather than simulating a new routing decision.

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 says what to use it for (verify which agent/trigger wins, or capture the structured skip reason), gives the safe default (send_mode='draft'), names the exact condition for the risky variant (send_mode='auto' on a test account to verify delivery), and points to blockchain_tx_data for a different event type. Nothing is left to inference.

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 this is a non-read-only write (readOnlyHint=false), non-idempotent (idempotentHint=false), and non-destructive, so the safety profile is covered. The description adds the scoping detail that the run was 'handed to you by DialogBrain,' but does not explain side effects of reporting, whether it can be called twice safely despite idempotentHint=false, or what happens afterward.

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 tight sentences that front-load the core purpose before the call trigger. Nothing is redundant, though the second sentence's 'Call this when you finish processing it' is slightly generic.

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 four-parameter reporting tool with annotations covering the safety profile and no output schema needed, the description covers what the tool does and when to invoke it. It could be stronger on post-call behavior and non-idempotency implications, but nothing critical for correct invocation is missing.

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 all four parameters (success, summary, trace_id, in_workspace) are already documented in the schema. The description adds no parameter-level meaning beyond that, which is the expected baseline when the schema does the heavy lifting.

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 a specific verb ('Report') and the resource/event being reported ('an agent run ... is over'), enumerating the two origin flavors (Claude Code agent task, external agent run). It is clear enough to distinguish from most siblings, though it doesn't explicitly contrast with tools like agent_handoff or agents_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?

'Call this when you finish processing it' gives an explicit trigger condition tied to task completion. There is no when-not guidance or named alternative (e.g., what to use if the task failed or was abandoned), but the activation context is unambiguous.

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 readOnly/idempotent/non-destructive, so the safety profile is covered. Beyond that, the description discloses non-obvious behavior: LLM system_prompt and prompt_messages are stripped by default, include_llm_bodies=true triggers a WARNING-level audit log, full=true disables truncation, and completion_text is capped at 8 KB. This is substantial disclosure the annotations do not carry.

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?

Purpose and payload are front-loaded in the first sentence, followed by cost semantics, usage routing, then option defaults. Dense and nearly waste-free, though three paragraphs is longer than strictly needed for a single-trace getter and some field detail (per-token names) could have been left to the payload itself.

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?

There is no output schema, so the description carries the return-value burden and does so: it names the span fields, explains cost_usd's 0-vs-null distinction, and covers token-level fields. For a 5-param read tool with full schema coverage, an agent has everything needed to call and interpret 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%, so the schema already documents each parameter; the baseline would be 3. The description adds marginal-but-real semantics: include_llm_bodies is for 'diagnosing prompt engineering issues' and its audit consequence, and full is framed as a 'human operator' escape hatch rather than a routine option.

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 a specific verb and resource ('Fetch the full execution detail for a single trace') and enumerates the payload (tool executions, events timeline, LLM spans with error_message, cost). It is immediately distinguishable from agents_traces_list (enumeration) and agents_traces_stats (aggregates), which appear as siblings.

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 explicitly says 'Use after agents.traces_list identifies a specific trace of interest (failed run, slow run, unexpected outcome)', naming the upstream sibling and the triggering conditions. The agent knows both the prerequisite call and the scenarios that select 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description still adds real behavioral context: the response fields (returned_count, dropped_on_page, has_more), what a non-zero dropped_on_page implies, and the tricky edge case where a fully deduped page returns returned_count=0 with has_more=true and requires re-calling with offset += limit. That is exactly the kind of operational nuance annotations cannot express.

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 usage, then filters, then return-shape caveats — a logical progression with no filler sentences. It is on the longer side, but nearly every clause carries actionable information, so the size is defensible.

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 takes on the burden of explaining the return shape and does so (returned_count, dropped_on_page, has_more) plus the pagination edge case and recovery step. Combined with the filter inventory and the pointer to agents.trace_get, an agent has everything needed to call and interpret this 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 description coverage is 100%, so every parameter is already documented in the schema, and the description's filter paragraph largely restates it (status, success, source, date range, limit/offset). It adds modest consolidation value by grouping the filters in one place, but no new semantics such as default behavior or interaction rules. 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?

States a specific verb and resource ('List recent execution traces for an agent') and immediately scopes it ('scoped to one agent'), plus maps it to a known surface (/admin/requests). It also names the sibling that provides the complementary capability (agents.trace_get), so an agent can distinguish it from agents_traces_stats and agents_activity without opening a schema.

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?

Gives explicit triggering scenarios — an agent call timed out, a wrong draft, or latency investigation — and explicitly routes to agents.trace_get for per-trace detail. That is a clear when-to-use plus a named alternative, leaving little to inference.

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?

Goes well beyond the readOnly/idempotent annotations by disclosing data caveats: spend reads 0 for runs predating per-agent attribution, null means the lookup could not run, the window is capped at 30 days to match the ClickHouse request_traces TTL, and matching is exact with 'no substring bleed'. These are non-obvious behaviors an agent needs.

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 the purpose and output inventory, then the spend semantics, then usage guidance. Dense and mostly waste-free, though the spend paragraph is on the longer side for a single returned field.

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 carries the burden of describing returns and does so by enumerating the aggregate metrics and spend fields, including the subtle own_key_cost_usd relationship. An agent has everything needed to call it and interpret the result.

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 baseline is 3, but the description adds real meaning: the rationale for the `days` cap (ClickHouse TTL) and the exact-match scoping of `agent_id` ('no substring bleed'). It stops short of explaining `in_workspace`, but the schema already covers it.

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?

Opens with a specific verb+resource ('Aggregated trace statistics for one agent') and enumerates the exact fields returned (runs, success rate, avg duration, error breakdown, top tools, histogram, spend). This clearly distinguishes it from the sibling trace tools that return individual records.

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 says when to use it ('bird's-eye view of an agent's health') and names the alternatives it complements ('before diving into individual traces with agents.traces_list / agents.trace_get'), with the routing condition stated rather than implied.

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 safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false), so the description's remaining burden is light. It contributes the trigger-type activation semantics, but says nothing about persistence, default enabled state, draft/send_mode interactions, or what happens on repeat calls — all of which matter for a mutating tool.

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?

Six short lines, purpose front-loaded, zero filler prose. Minor waste: the trigger-type bullet list duplicates (and under-represents) the schema enum, so it earns less than a full 5.

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 an 11-parameter mutating tool with a nested conditions object, the description is thin, but the schema carries essentially all parameter detail, so the gap is mostly the unstated return value (no output schema exists) and the incomplete type enumeration (4 of 9 enum values, missing incoming_call, job_completed, calendar_event, blockchain_event, lead_captured).

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 schema fully documents all 11 parameters (including the very detailed `conditions` object); baseline 3 applies. The description adds no parameter meaning of its own, and its four-item type list is narrower than the nine-value enum, so it does not compensate further.

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?

States a specific verb (create) and resource (trigger) plus the owning entity (AI agent), and adds that triggers determine when an agent activates. It is clearly distinguishable from agents_create and agents_trigger_update, though it never names a sibling explicitly.

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 type list implies when each trigger fires, which gives some usage context, but there is no explicit when-to-use guidance, no mention of prerequisites (the agent must already exist), and no routing to agents_trigger_update / agents_trigger_delete for modifying or removing triggers.

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 annotations already declare destructiveHint=true and idempotentHint=true, so the agent knows this is destructive and idempotent. The description adds the irreversible nature ('cannot be undone'), which is useful but partly redundant with destructiveHint.

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 very short sentences, zero waste, and the warning is front-loaded after the core purpose.

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, the description covers purpose and irreversibility, which is adequate. However, it doesn't mention required permissions or side effects beyond deletion, and there's no output schema to rely on.

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 fully documents parameters. The description adds no parameter syntax or constraints, 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 a specific verb and resource: 'Delete a trigger from an AI agent.' It clearly distinguishes this tool from siblings like agents_trigger_create and agents_trigger_update, which perform different operations on the same resource.

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 (to delete a trigger) but doesn't provide explicit when-to-use or when-not-to-use guidance, nor does it reference alternatives such as agents_trigger_update for modification.

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=false, destructiveHint=false, idempotentHint=false, so the safety profile is covered. The description adds patch semantics (unlisted fields are preserved), which is genuine behavioral value. But it omits a key hazard disclosed only in the schema — that conditions are fully REPLACED, and that thread_ids/excluded_thread_ids merge into conditions — which matters given destructiveHint=false.

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, well front-loaded: the action first, then the update semantics. Efficient, though the second sentence is partly inaccurate relative to the schema's required fields, so it does not fully earn 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?

For a 12-parameter mutation tool with nested objects and no output schema, the description is minimal — the massive conditions schema does nearly all the work. It neither routes the agent away from trigger_create/delete nor warns about the destructive conditions/replacement behavior, leaving the definition only barely sufficient.

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% and the parameter descriptions are unusually rich (merging behavior, deny-list precedence, phone-number matching), so the schema carries the burden and baseline 3 applies. The description adds no parameter-level meaning beyond that, and its "all parameters are optional" statement is inaccurate against the required trigger_id/agent_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?

States a clear verb+resource ("Update an existing AI agent trigger") that plainly tells the agent what the tool does. However, it does no sibling differentiation — agents_trigger_create, agents_trigger_delete, and agents_update all sit nearby, and the description never distinguishes between 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?

"only provided fields will be updated" implies partial-update usage, but there is no explicit when-to-use vs agents_trigger_create or agents_trigger_delete, and no prerequisites or exclusions. Notably, the claim that "all parameters are optional" conflicts with the schema's two required fields (trigger_id, agent_id), which makes the usage hint misleading.

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 partial-update semantics ('only provided fields will be updated'), which annotations do not state, and that is useful for understanding the mutation behavior. However, it omits that several parameters (prompt_text, allowed_tools, voice_tools) destructively replace entire surfaces, and the claim that 'All parameters are optional' is inaccurate given the required agent_id.

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 purpose and partial-update note are front-loaded, and the bulleted capability list is scannable and earns its place as a high-level map of an 85-parameter tool. It is neither bloated nor redundant.

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 extensive schema coverage and the absence of an output schema, the description provides sufficient orientation for an update tool: it states the scope, optionality, and major update categories. A warning about destructive replacements would improve it, but the schema carries that detail.

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 schema already documents all 85 parameters in detail; the description adds no syntax or format guidance beyond grouping use cases. Its assertion that all parameters are optional conflicts with the required agent_id, though the schema corrects this.

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 a specific verb ('Update') and resource ('AI agent's configuration'), so the action is unambiguous. It does not name or distinguish itself from siblings like agents_create or agents_update_from_template, leaving the agent to infer the boundary from the tool name alone.

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:' list gives concrete update scenarios (enable/disable, change name, assign prompt, replace knowledge collections, etc.), providing clear context for when the tool applies. It stops short of naming alternatives or when-not-to-use conditions, which would be needed for 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?

Goes well beyond the annotations by disclosing what is destroyed (prompt_text overwritten, customizations replaced), the recovery path (prompt history), and what is untouched (tool/model/execution settings). The 'recoverable via prompt history' detail is fully consistent with destructiveHint=false.

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?

Purpose is front-loaded in the first sentence, followed by when-to-use and then the destructive/scope caveats. Every sentence carries distinct information; nothing is redundant.

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 mutation tool, the critical behavioral facts (what changes, what is preserved, recoverability, applicability scope) are all covered, and the annotations already carry the safety profile. No output schema is needed, and nothing an agent requires to call it correctly is missing.

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 are already documented. The description still adds a meaningful constraint on the agent_id parameter — it must reference a forked agent, not a from-scratch agent or a template — which sharpens selection beyond the raw 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?

States a specific verb (update) and resource (a forked agent's instructions/prompt) and a precise target (the latest version of the system template it was created from). This is clearly distinguishable from siblings like agents_update or agents_prompt_restore.

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?

Explicit when-to-use ('when the platform has improved a template and the user wants their forked agent to pick up the new prompt') plus an explicit when-not ('only works on agents forked from a template — not from-scratch agents or templates themselves'). Nothing is left to inference.

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 the write/open-world/non-idempotent profile, and the description adds genuinely new behavioral context: the creation-time call to the Voyage AI embedding API, that the description field is frozen into a reference vector, and the cosine-similarity matching model. It does not disclose failure modes (e.g. embedding API errors) or the returned object, but it goes meaningfully 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?

Front-loaded with purpose, then mechanism, then per-field guidance in bullets, which is easy to scan. It is somewhat long and partially repeats the schema's threshold examples and the description example, but each section still carries usable 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?

For a mutation tool with no output schema, the description covers the mental model, the critical input, tuning semantics, and the external API dependency. The main omission is what the call returns (filter id/object) and any workspace-scoping caveat, though the in_workspace parameter is self-documenting in the schema.

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 already 100%, but the description adds interpretive meaning: it explains that the description field becomes the reference embedding and is the most important input, with concrete example phrasings, and it translates threshold numbers into sensitivity behavior (0.3 permissive vs 0.8 strict). This exceeds the schema's own wording for these two params.

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?

States a specific verb and resource ('Create a new AI filter') and immediately scopes it to 'semantic intent-based message matching', which cleanly separates it from ai_filters_update, ai_filters_delete, ai_filters_list, and ai_filters_test. An agent can identify the operation without opening the schema.

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 rich guidance on how to configure the tool (what to write in the description field, how threshold values behave) but never states when to create a filter versus when to list, test, or update one. Usage context is implied through the embedding workflow rather than stated, and no alternative sibling is named.

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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new consequence information: irreversibility and the cross-entity side effect that triggers referencing the filter by ID will stop matching, prompting follow-up work. It stops short of 5 because it says nothing about required permissions or the response shape.

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-loads the core action, then a scannable 'When to use' bullet, then the critical warning. Every sentence carries weight and none restates the tool name or annotations.

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 destructive single-entity delete with no output schema needed, the description covers irreversibility, downstream trigger breakage, and the use case. An agent has everything required to decide and act; the only minor omission is a pointer to ai_filters_list for obtaining IDs.

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 filter_id and in_workspace are already fully documented in the schema. The description adds no additional meaning about parameter format, ID acquisition, or workspace-scoping behavior, so the baseline 3 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?

Starts with a specific verb+resource ('Permanently delete an AI filter') that immediately distinguishes it from the create/list/test/update siblings in the ai_filters_* family. The word 'Permanently' additionally sets it apart from ai_filters_update, which an agent might otherwise confuse with removal.

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 an explicit 'When to use' block ('User wants to remove a filter they no longer need'), giving clear positive context for selection. It does not name alternatives or when-not-to-use conditions (e.g. disabling rather than deleting), so it falls short of the explicit routing a 5 requires.

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 readOnly/idempotent/non-destructive, so safety is covered; the description adds real value by listing the returned fields (id, name, description, threshold, is_active) in the absence of an output schema. It does not mention permissions, pagination, or limits, but for a scoped read tool this is solid.

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 purpose is correctly front-loaded, but the two-paragraph explanation of embeddings and cosine similarity is heavy for a list operation and repeats conceptual material an agent rarely needs to call the tool. The 'When to use' and return-field lines earn their place; the mechanics exposition is mostly filler.

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 explicit enumeration of returned fields is a meaningful completeness win, and the when-to-use guidance covers the main invocation contexts. Only the optional in_workspace override is left to the schema, which is acceptable given full schema coverage.

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?

There is one optional parameter (in_workspace) at 100% schema description coverage, so the schema fully carries its semantics. The description never references the parameter, so the baseline 3 for high-coverage schemas 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?

The first sentence gives a specific verb and resource ('List all AI filters for the current workspace'), and the following paragraphs define what an AI filter actually is versus keyword filters. It never names a sibling tool (ai_filters_create, ai_filters_test, ai_filters_update) explicitly, so differentiation is implied through the 'before creating a new one' framing rather than stated.

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 dedicated 'When to use' block gives three concrete scenarios: audit existing filters before creating, fetch filter IDs for trigger conditions, and review thresholds/active status. That is strong context, but there are no stated exclusions or explicit named alternatives (e.g. 'use ai_filters_test to test a filter'), which keeps it below 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=true. The description goes beyond them by disclosing the external Voyage AI embedding call (the reason openWorldHint is true), the exact computation performed, and the shape of the returned score. It stops short of noting latency, cost, or failure modes of that external call.

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-loads the core purpose, then layers mechanism, use cases, return contract, and a dependency note. Sections are clearly delineated and no sentence is filler; the external-API note prevents misreading this as a pure local computation.

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 supplies the return shape ({similarity, matched, threshold}), the match rule (similarity >= threshold), all required parameters, and the external dependency. Nothing an agent needs to call it correctly is missing.

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 filter_id, message, and in_workspace fully. The description adds conceptual context around how the message is embedded but no parameter-specific semantics beyond what the schema states, so baseline 3 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?

States a specific verb and resource ('Test a message against an AI filter') and immediately clarifies the mechanism (embedding + cosine similarity). It is trivially distinguishable from its CRUD siblings (ai_filters_create/update/delete/list) because 'test' is its own 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 explicit 'Use this to:' block enumerates three concrete scenarios — verify before wiring into a trigger, tune threshold on borderline messages, and debug production match/mismatch. This tells the agent both when and why to reach for this tool rather than the filter CRUD 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?

With annotations covering safety (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), the description still adds real behavioral context: partial-update semantics and, crucially, that changing the description triggers an external Voyage AI embedding call to regenerate the reference vector. This explains the non-idempotent hint rather than just repeating it. It does not discuss permissions or failure 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?

Front-loaded with the core action, then a scannable bulleted 'When to use' list and a clearly marked Note for the side effect. Efficient overall, though several bullets largely restate the fields already enumerated in the opening sentence.

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 6-parameter mutation tool with no output schema, the description covers the essential gaps: partial-update contract, minimum-field requirement, threshold direction, and the external embedding side effect. Only auth/permission requirements and error conditions are absent, which are minor for this tool class.

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 baseline is 3, but the description adds genuine semantic value the schema lacks: 'threshold (higher = stricter matching)' clarifies the direction of the similarity metric, and 'enable or disable a filter without deleting it' frames is_active's purpose. It does not touch in_workspace, which the schema already documents.

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?

States a specific verb (update) and resource (AI filter) plus the exact mutable fields (name, description, threshold, active state), which cleanly separates it from ai_filters_create, ai_filters_delete, ai_filters_list and ai_filters_test. An agent can identify the tool's role without opening the schema.

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' block gives explicit trigger conditions for each field, and it states the key constraint 'Provide only the fields you want to change. At least one field is required.' It stops short of naming alternatives (e.g., use ai_filters_create to make a new filter, ai_filters_delete to remove one), so the routing guidance is clear but not exhaustive.

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 cover the write/safe/idempotency profile (readOnly=false, destructive=false, idempotent=false). The description adds genuinely new behavior: applying an already-present tag flips its is_manual flag, which explains why the operation is not purely idempotent. Return format is undocumented but that is minor.

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 the core action, then a compact 'When to use' block, then the required inputs. Every sentence earns its place with no filler.

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 mutation tool whose safety profile is carried by annotations, the description covers action, triggers, required inputs, and the update-on-reapply behavior. Missing only edge-case handling (e.g., invalid tag_ids or the 1-20 limit noted in schema), which is minor.

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 all three parameters including in_workspace. The description restates thread_id and tag_ids but adds no format, constraint, or syntax detail beyond the schema, so baseline 3 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?

States a specific verb (apply) and resource (AI tags to a thread), so an agent can tell what it does at a glance. It does not explicitly distinguish itself from siblings like ai_tags_remove_from_thread or ai_tags_list, so it stays just below the top band.

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 gives two concrete triggering scenarios (labeling a conversation, categorizing/tagging a thread). There are no explicit exclusions or named alternatives, but the use context is clearly stated.

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 this is a non-read-only, non-idempotent create. The description adds meaningful behavior beyond them: the classifier runs on every incoming message and auto-labels matching threads, and there is a hard quota (20 personal / 50 team tags). It stops short of saying what happens at the limit or on duplicate names.

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?

Purpose is front-loaded in the first sentence and the thread-classifier mechanism follows immediately. The tips and limit sections are useful rather than filler, though the block is longer than strictly required for a 6-param create call.

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 exists, and the description never indicates what creation returns (e.g., the new tag id), which is the one real gap. Everything else an agent needs — semantics, quota constraints, field guidance — is covered, so it is close to complete for this complexity level.

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 baseline is 3, but the description meaningfully extends the 'description' parameter with guidance on writing classifier criteria and examples ('Messages reporting errors, crashes...'). That is real semantic value the schema text alone does not carry.

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 a specific verb and resource ('Create a new AI tag') and goes further by defining what an AI tag actually is ('lightweight classifiers that run on every incoming message'). An agent understands both the operation and the artifact it produces, which is enough to distinguish this from ai_tags_update/delete/list without opening a schema.

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?

There is an explicit 'When to use' section with two concrete scenarios (auto-classify incoming messages; reduce agent cost via pre-filtering). However, it offers no when-NOT-to-use guidance and never mentions the sibling ai_filters_create, which an agent could easily confuse with 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?

Annotations already declare destructiveHint=true and idempotentHint=true, but the description goes further with concrete consequences the annotations cannot express: cascading removal of all thread associations, explicit irreversibility ('This cannot be undone'), and the important negative that threads themselves are preserved. This is exactly the 'what gets destroyed' context the annotations lack.

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 core action and its cascade effect are front-loaded in the first two sentences, and the destructive warning is placed last for emphasis. The 'When to use' header with a single bullet is mild structural overhead, but nothing is padded or redundant.

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 no-output-schema mutation tool whose annotations cover the safety profile, the description supplies the missing cascade and irreversibility semantics. It stops short of stating failure behavior (e.g. nonexistent tag_id) or permission requirements, which are the only remaining 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 description coverage is 100% with only two parameters, so tag_id and the workspace override are already fully documented in the schema. The description adds no syntax, format, or constraint detail for either parameter, so the baseline 3 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?

Specific verb + resource ('Delete a personal AI tag') with an explicit scope qualifier ('personal'), which separates it from ai_tags_create, ai_tags_update, and especially ai_tags_remove_from_thread. The closing sentence 'Threads are NOT deleted — they just lose this tag' resolves the exact ambiguity the sibling name could otherwise 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 'When to use' block states a clear trigger condition ('User wants to permanently remove a tag they no longer need'). It also implicitly disambiguates from ai_tags_remove_from_thread by clarifying that threads survive the operation, but it never names that alternative tool or states when not to use this one.

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, non-destructive and closed-world, so the safety profile is covered. The description adds value beyond that by explaining the classification mechanism and, most usefully, the exact scope of the returned counts ('non-archived, included threads only'). It does not state whether counts are real-time or cached, which is the only remaining gap.

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 the core purpose, then a scannable bulleted usage block, then return semantics. The middle explanatory paragraph on classifier cost is longer than strictly needed for tool selection but does carry real context, so it mostly 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?

With no output schema, the description carries the burden of return values and does so ('all tags with thread counts, non-archived, included threads only'), plus usage triggers and the tag domain model. Nothing needed to call it correctly is missing, aside from per-parameter detail that the schema already supplies.

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% and both parameters are documented in-schema, including the enum meaning for applies_to and the non-persistent semantics of in_workspace. The description adds nothing about either parameter (it never mentions the thread/task filter or cross-workspace execution), so the baseline 3 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?

The description opens with a specific verb+resource ('List all personal AI tags') and then defines what an AI tag actually is (automatic message filters applied by a lightweight classifier). It differentiates itself from siblings by naming the create and add/remove_from_thread workflows it feeds into, so an agent can place it in the tag lifecycle without opening another schema.

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?

An explicit 'When to use' block lists three concrete triggers: pre-checking before creating a tag, retrieving tag IDs for add_to_thread / remove_from_thread, and inspecting per-tag thread counts. The relationship to sibling tools is stated, so the routing decision is unambiguous.

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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the mutation/idempotency profile is covered. The description adds that this un-associates a tag from a thread ('un-label') rather than deleting it, which is useful, but says nothing about permissions, side effects, or what happens to other threads using the same tag.

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 short lines, front-loaded with the action, followed by scannable bullets and a one-line input reminder. No filler.

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 scoped tag-removal tool with a full schema and annotations covering the safety profile, the description gives enough to invoke correctly. The only gap is the un-explained in_workspace parameter, which is covered by the schema anyway.

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 tag_id, thread_id and in_workspace are already documented in the schema. The description only restates that thread_id and tag_id are required and adds no format, range, or scoping detail (in_workspace is never mentioned). 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?

States a specific verb and resource: 'Remove a specific AI tag from a thread.' The wording 'un-label / remove from a conversation' implicitly separates it from sibling ai_tags_delete (which removes the tag itself) and ai_tags_add_to_thread (the inverse). An agent can identify the operation without opening the schema.

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 dedicated 'When to use' block with two concrete scenarios (un-labeling, correcting a misapplied tag) and states the required inputs. However, it does not name an alternative tool or state when-not to use it (e.g., ai_tags_delete when the tag should be destroyed).

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 safety profile (not read-only, not destructive, not idempotent, closed-world). The description usefully adds partial-update semantics ("Provide only the fields you want to change. At least one field is required"), which is real behavioral context. It does not mention permission requirements, reversibility, or side effects of disabling, so it stays at a moderate level.

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?

Purpose is front-loaded in the first sentence, followed by a scannable "When to use" list and a closing constraint sentence. Every line earns its place with no redundancy, though the bullets restate field names already implied by the opening sentence.

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 mutation tool with a title annotation, full schema coverage, and no output schema, the description covers purpose, selection cues, and the partial-update contract adequately. It is only slightly incomplete in not addressing sibling routing (create vs. delete vs. add/remove-from-thread) that an agent choosing among ai_tags_* tools would want.

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 per-parameter meaning is already fully carried by the schema (including OMIT-to-leave-unchanged and enum values). The description only adds the cross-parameter constraint that at least one field must be supplied, which is marginal added value over the schema, so baseline 3 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?

The description gives a specific verb+resource ("Update an existing personal AI tag") and enumerates the mutable fields, so an agent immediately knows what it does. It implicitly separates itself from create/delete/list siblings via "existing" and "update", but never names an alternative to disambiguate against 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 explicit "When to use" bullets map user intents (rename, change icon/color/description, enable/disable) to this tool, which is clear context for selection. It stops short of the 5-level bar because it never states when NOT to use it or names the create/delete siblings that a user might also be reaching for.

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, destructiveHint=false, and openWorldHint=false, so safety is covered structurally. The description adds value beyond that by disclosing the return shape ('Returns rows plus a chart hint') and the current-workspace scoping, which the annotations do not convey.

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, purpose front-loaded, examples inline, and the return/scoping caveats tacked on last. No filler or repetition; every clause carries 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?

With no output schema, the description usefully notes 'Returns rows plus a chart hint,' and the workspace scoping plus read-only nature round out the picture for a 2-parameter NL query tool. Minor gaps remain around row limits or result shape detail, but nothing essential to correct invocation is missing.

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 both parameters are already documented in the schema (including the in_workspace semantics about not storing anything and not affecting other sessions). The description's examples mirror the schema's own example for 'question' and add no new parameter-level syntax or constraints, so baseline 3 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?

States a specific verb (Answer analytics questions) and resource (this workspace's own data: conversations, messages, voice calls), with two concrete example questions that pin down the scope. It is readily distinguishable from data-access siblings like db_query, knowledge_query, and threads_channel_account_stats.

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 'about this workspace's own data' framing and the example questions give clear context for when to reach for it, and the read-only/current-workspace scoping tells the agent it is safe for exploratory analytics. It stops short of naming alternatives (db_query, search_messages) or stating when NOT to use it, so it lacks explicit 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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so safety is covered. The description adds genuine non-obvious context by disclosing the implementation strategy (HOME key + am kill, never am force-stop because it corrupts PackageManager), which tells the agent what actually happens to the device 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?

Front-loaded with the core action, followed by a compact parenthetical on the safe method and an example. Every element is short and purposeful, though the example clause is slightly redundant with the schema's own package example.

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 single-action device control tool with no output schema and full parameter coverage, the description supplies purpose, method, and the key safety caveat. It omits edge cases such as behavior when the app isn't installed or running, but nothing critical for correct invocation is missing.

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 package, in_workspace, and channel_account_id in detail. The description only repeats the package example ('com.whatsapp'), which the schema already supplies, adding nothing extra. Baseline 3 applies when the schema does the heavy lifting.

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 a specific verb (close) and resource (an app on the Android device), making it immediately distinguishable from siblings like android_launch_app or android_current_app. The scope and effect are unambiguous without opening any schema.

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 clarifies the internal mechanism and rules out am force-stop, but never states when to prefer this over android_shell or other alternatives, nor any prerequisites (e.g. app must be running). Usage is implied rather than 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond that (no statement about the return format, staleness, or whether the device must be unlocked), so it clears the lower bar set by annotations but adds little.

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?

A single front-loaded sentence with zero filler; the resource is identified immediately and nothing is repeated from the title or 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?

For a simple read-only query tool with full annotation coverage and no output schema, the description tells the agent what it retrieves (app plus activity), which is enough to call it correctly. It could note that results reflect a single device when multiple are connected, but the schema already handles that.

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% and both parameters (in_workspace, channel_account_id) are fully documented in the schema, including the multi-device ambiguity rule. The description adds nothing about parameters, so the baseline of 3 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?

Specific verb ('Get') plus a precise resource: the currently focused app and activity. This implicitly separates it from android_list_apps (enumerates all apps) and android_ui_dump (dumps the UI tree), but it never names those siblings explicitly, so it falls short of a 5.

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 states what the tool returns but gives no guidance on when to reach for it versus android_list_apps, android_ui_dump, or android_screenshot, nor any prerequisites or exclusions. Usage must be inferred entirely from the name.

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 destructive/not-idempotent, but the description adds non-obvious behavior beyond them: the 300MB cap, that large installs take minutes, and critically that a timeout does NOT cancel the install (it keeps running on the device). That async semantics disclosure is exactly the kind of context annotations cannot convey.

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-loads the core action, then the input options, then the timeout caveat. Dense with parenthetical asides but each sentence carries actionable content; slightly long for the amount of core instruction.

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 and 6 optional params, the description covers what an agent needs: inputs, size limits, reinstall semantics, and the failure/verification path. The device-disambiguation requirement lives in the channel_account_id schema description, so nothing material is missing.

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 carries the parameter burden (baseline 3). The description still adds value beyond it: the 300MB size ceiling and the APK/XAPK/APKS split-bundle framing, plus reinforcing the apk_url-over-base64 preference. Modest but real addition.

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?

States a specific verb (install) and resource (app/APK on the Android device), and even clarifies the artifact types supported (APK/XAPK/APKS). An agent can distinguish it from android_launch_app (launch installed app) and android_list_apps (verify install) without opening schemas.

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 routes between apk_url (preferred, only workable option for real apps) and apk_base64 (tiny payloads only), tells when to set reinstall=true (signature changes), and gives the alternative path on timeout: verify with the app-list tool rather than re-installing. No inference required.

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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the keycode naming convention (a parameter concern) and discloses nothing extra, such as which app/foreground context receives the event or that BACK/HOME may discard in-app 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 short sentences, front-loaded with the action and followed immediately by the accepted input forms. Efficient, though the second sentence partly restates what the schema's 'code' description already provides.

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 single-action tool with 100% schema coverage and full annotations, the description covers the action and the input convention adequately. Device-selection ambiguity and failure behavior are handled by the schema, so no critical gap remains for correct 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%: the schema already documents 'code' with the numeric/name list and fully explains in_workspace and channel_account_id (including the ambiguity-rejection rule). The description's examples ('3' for HOME, '4' for BACK, 'HOME') largely duplicate the schema, so baseline 3 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?

States a specific verb and resource ('Send a key event to the Android device'), which clearly separates it from android_tap, android_type, and browser_press_key. It does not, however, explicitly name which sibling to prefer for navigation-key input versus text/tap input.

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 the two accepted input forms ('keycode ... or common name'), which implicitly signals it is for hardware/navigation keys rather than UI targeting. It never states when to use this instead of android_tap, android_type, or android_shell, so the selection guidance is only implied.

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=false, destructiveHint=true, openWorldHint=true, and idempotentHint=false. The description adds only that it returns success status and a process ID if launched; it does not explain what makes the operation destructive or mention auth or rate-limit considerations.

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 short sentences, front-loaded with the action and followed by a compact example and return note. It avoids filler and is appropriately sized for a simple tool.

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 3-parameter launch tool with full schema coverage and annotations covering the safety profile, the description covers the action and return values adequately. It omits device-selection prerequisites and destructive-behavior detail, but those are already in the schema and annotations.

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%, and the schema already documents each parameter, including the same 'com.whatsapp' example and the channel_account_id ambiguity rule. The description's example adds no 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 states a specific verb and resource ('Launch an app') plus the Android device context and a concrete package-name example. It does not explicitly name sibling alternatives like android_install_apk or android_close_app, but the action verb 'launch' inherently distinguishes it from install/close/list tools.

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 when-to-use or when-not-to-use guidance, no prerequisites, and no named alternatives. The agent must infer usage entirely from the tool name and the sibling list.

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 readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds one genuine behavioral fact beyond the annotations: the default result set is third-party apps only. It says nothing about ordering, volume, or response shape.

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 tight sentences, front-loaded with what the tool does and then the default-vs-override behavior. No filler and nothing to trim.

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 no-required-parameter read tool with 100% schema coverage and annotations covering safety, the description is nearly complete. Return fields are undocumented, though there is no output schema and a list of apps is largely self-explanatory.

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 all three parameters (all, in_workspace, channel_account_id) are already documented in the schema. The description only restates the `all` semantics, adding no meaning beyond what structured data provides. Baseline 3 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?

States a specific verb+resource ('List installed apps') scoped to 'the Android device', which naturally separates it from android_launch_app, android_close_app and android_ui_dump. It is clear on its own, but never explicitly differentiates itself from any sibling tool.

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 one useful routing rule ('use all=true for all apps') and states the default scope, but offers no guidance on when to reach for this tool versus alternatives such as android_ui_dump. Usage is implied rather than explained.

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=false, so the safety profile is covered. The description usefully adds the output encoding (JPEG as base64), but says nothing about resolution, latency, or whether the capture includes overlays — modest added value over the 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 short sentences, zero filler, with the action stated first and the return format second. Nothing could be removed without losing 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?

With no output schema, the description correctly compensates by stating the return type and encoding. Given the low complexity (2 optional params, fully documented) and the annotation coverage, the definition is nearly complete; only device-selection context is missing.

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 both parameters (in_workspace, channel_account_id) are already fully documented in the schema, including the ambiguity-rejection rule. The description adds no parameter-level meaning, which is the expected baseline here.

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?

States a specific verb+resource ("Capture a screenshot from the Android device") and adds the return format, which clearly separates it from browser_take_screenshot and android_ui_dump. It does not name the sibling it replaces, but the Android-device scoping makes the domain 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?

There is no guidance on when to prefer this over android_ui_dump (structured view hierarchy) or browser_take_screenshot (web pages), nor any note about the multi-device ambiguity case. The only selection hint lives in the channel_account_id schema text, not in the description.

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 idempotentHint=true, but the description explicitly licenses state-changing commands (input, am, pm, settings, content, monkey) which modify the device and are not idempotent. The description therefore contradicts the safety annotations rather than reinforcing them.

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 tight sentences: purpose first, then the binding constraint. The 15-item allowlist is bulky but every token is required information, and nothing is redundant with 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?

There is no output schema, so return-format omissions are acceptable, and the core allowlist constraint is covered. But for a shell-execution tool the description is silent on timeouts, output capture/truncation, error behavior when a command is not allowlisted, and what execution context the command runs in.

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 baseline is 3, but the description adds a real constraint the schema omits: the first element of cmd must be on a fixed allowlist, effectively an implicit enum of valid values. It does not, however, clarify the string-vs-array type handling beyond what the schema already documents.

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?

States a specific verb and resource ('Run an allowlisted shell command on the Android device') and immediately scopes it with the command allowlist. An agent can distinguish this generic shell escape hatch from the dedicated action tools (android_tap, android_type, android_screenshot) without opening the schema.

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 states the allowlist but gives no when-to-use guidance and never mentions the sibling alternatives that overlap (android_tap, android_type, android_screenshot, android_ui_dump). Nothing tells the agent when to reach for android_shell versus those dedicated 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?

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds no behavioral context beyond what the annotations provide — it doesn't explain why a swipe is flagged destructive or how the swipe interacts with device 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 sentences, front-loaded with the core action, zero padding. Slightly weakened by the vague "etc." tail but otherwise 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?

Adequate for selection given full schema coverage and annotations, but it omits how to choose between android_swipe and android_tap, and gives no coordinate-system or duration context beyond the schema. Complete enough to invoke, not enough to route confidently.

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 fully documents all 7 parameters including duration_ms default and the channel_account_id requirement. The description adds no syntax, coordinate-system, or format detail beyond the schema, so the baseline 3 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?

States a specific verb (swipe/drag) and resource (Android device screen) with the coordinate-to-coordinate scope. The verb naturally distinguishes it from siblings like android_tap or android_key, though no sibling is named explicitly.

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?

"Use for scrolling, opening app drawer, etc." gives implied usage scenarios but no explicit when-to-use-vs-alternatives guidance (e.g., when to swipe instead of android_tap). The trailing "etc." leaves the boundary fuzzy.

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 destructiveHint=true, readOnlyHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds essentially nothing beyond that: it does not warn that a tap can trigger irreversible UI actions, and its only extra content (device pixel coordinates) merely restates the schema.

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 the action and the unit front-loaded, zero filler. Nothing to trim without losing 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?

For a simple four-parameter tap with full annotations and complete schema descriptions, the core is adequate. What is missing is workflow context: how to obtain the coordinates and how this differs from android_swipe, which an agent driving a device would need.

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%, including the nuanced channel_account_id ambiguity rule and the in_workspace scoping note, so the schema carries the parameter burden. The description's coordinate-unit remark duplicates the x/y descriptions rather than adding meaning, so the baseline 3 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?

The description names a specific verb (Tap), a target (Android device screen), and the coordinate unit (device pixels), so the agent knows exactly what the tool does. It does not, however, distinguish itself from the closest sibling android_swipe or place itself in the android_* family workflow.

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?

There is no when-to-use guidance: nothing says when to prefer android_tap over android_swipe or android_shell, nor that coordinates typically come from a prior android_screenshot/android_ui_dump. The agent must infer the workflow entirely on its own.

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 destructiveHint=true, openWorldHint=true, and idempotentHint=false, so the safety profile is covered. The description adds nothing beyond the name: it does not say whether existing text is replaced, whether a field must be focused first, or what happens on failure, which matters for a destructive typing action.

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?

A single efficient sentence with the action front-loaded and zero waste. It is terse to the point of under-specification, but structurally sound.

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 input tool with full schema coverage and annotations carrying the safety profile, the minimal description is close to adequate. It is missing the key operational context that a text field must be focused and that typing may overwrite existing content, which the destructiveHint implies but the text never confirms.

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%, and the descriptions are rich (channel_account_id documents the ambiguity rejection, in_workspace documents scoping). The description contributes nothing about parameters, so the baseline of 3 is correct.

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?

States a specific verb (type) and resource (text on the Android device keyboard), which is clearly distinct from android_tap, android_swipe, and android_shell. It does not, however, explicitly distinguish itself from the closely related android_key or browser_type siblings.

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