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

Given no annotations, the description fully compensates: discloses return value (`final_answer`), error handling (do not re-trigger), delegation behavior with `agent_id` (spawns new trace), and model override fallback logic.

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

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

Three sentences, front-loaded with purpose, then usage notes and error handling. No redundant information, every sentence serves a 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?

Given the tool's complexity (multi-step delegation, return format, error scenarios), the description covers all necessary aspects. No output schema but the return value is explained.

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%, baseline 3. Description adds valuable context: explains model override behavior when `agent_id` is set, describes trace linking for `agent_id`, and clarifies task_description should include all context.

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

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

Description clearly states the tool delegates multi-step tasks to a planner and is for complex asks. It distinguishes from sibling tools by its unique purpose but does not explicitly differentiate from all 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?

Explicitly states when to use (when more than a direct answer is needed) and provides a clear don't-re-trigger condition for timeout/error results. Does not list alternative tools but the context is sufficient.

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

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

No annotations are provided, so the description carries full burden. It discloses that files are agent-specific and not shared, and explains the async behavior where chunk_count returns 0 until indexing completes. This adds meaningful behavioral context beyond the schema, though it could be more comprehensive (e.g., permissions, idempotency).

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

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

The description is well-structured with a numbered workflow and clear sections. It is concise (5 sentences) with no filler, front-loads the purpose, and every sentence adds value.

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

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

For a tool with only 2 parameters and no output schema, the description is remarkably complete. It covers prerequisites, workflow, return value behavior (chunk_count 0 while processing), and follow-up actions, leaving no significant gaps.

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

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

Schema coverage is 100% with both parameters described. The description adds workflow context (e.g., file_id from upload/ingest) but does not significantly enhance the parameter meanings beyond the schema. Per rubric, baseline is 3 for high coverage.

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

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

The description clearly states the tool's purpose: 'Attach a file to this agent's private knowledge (agent-specific files, not shared with other agents).' This uses a specific verb ('attach') and resource ('file to agent's knowledge'), and distinguishes it from siblings like agents_remove_file and agents_list_files.

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

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

The description provides a detailed 3-step workflow (upload, index, attach) and notes that chunk_count shows 0 while processing, with a follow-up suggestion to use agents.list_files later. It implicitly tells when not to use (must have uploaded and ingested first) and gives explicit steps, fully guiding the agent.

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

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

With no annotations, the description carries full responsibility. It discloses that the action sends a message to a real person and that text can be optionally edited. This is a critical behavioral trait for an irreversible 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?

The description is concise with only 4 sentences plus a list of examples. It is well-structured, front-loading the main purpose, and every sentence adds value.

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

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

For a simple tool with 2 parameters and no output schema, the description covers purpose, usage triggers, and a critical warning, making it 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?

The input schema provides full coverage with descriptions for both parameters. The description adds context by mentioning optional editing, but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Approve a pending agent draft and send the message.' It uses specific verbs and resources, and the list of example user phrases helps distinguish this from siblings like agents_reject_draft.

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

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

The description explicitly lists example user phrases that trigger use, and it warns about sending to a real person. However, it does not explicitly state when not to use the tool or mention alternatives beyond the implied rejection sibling.

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 no annotations, the description carries full burden. It discloses execution time (10-60s), explains the return value in detail, and describes the agent's behavior (runs with configured prompt, tools, knowledge). It lacks explicit safety/permission info but is otherwise transparent.

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

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

The description is somewhat lengthy but well-structured: purpose first, then return format details. Every sentence adds value, though some output details could be condensed. No wasted words.

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

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

Given no output schema, the description provides a complete return format, including edge cases like 'silent' status and attachment-only sends. It covers timing, parameters' effect on output, and execution mode. Thorough and 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 coverage is 100%, so parameters are already described. The description adds value by clarifying send_mode's default behavior and its independence from execution_mode, going beyond the schema. No additional semantics needed for message and 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?

The description clearly states the tool sends a message to an AI agent and gets its response, and distinguishes it from sibling tools like agent_handoff by specifying 'test agents or have them process a task'. It uses specific verbs and resources.

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

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

The description explicitly says 'Use this to test agents or have them process a task', providing clear usage context. It does not explicitly mention when not to use or list alternatives, but the sibling names imply distinction.

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 no annotations, the description must disclose behavioral traits. It explains the behavior of execution modes (two-phase AI, autonomous planning, simple pattern matching). However, it omits authorization needs, rate limits, side effects, and return value. Since no output schema exists, return format is unclear.

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 fairly concise and front-loads the main purpose. The bullet-like list of execution modes uses clear formatting. Minor redundancy exists (e.g., mentioning default in both description and schema) but overall 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?

Given the tool's complexity (5 params, 2 enums, no output schema), the description covers the main purpose, execution modes, and parameter context well. Missing return value and error handling, but the richness of mode explanations compensates.

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

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

Schema coverage is 100%, but the description adds substantial value beyond the schema. It elaborates on execution modes with detailed explanations and best-use scenarios, which are not present in the schema's enum descriptions. This helps the agent select the correct mode.

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

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

The description clearly states 'Create a new AI agent in the workspace.' It specifies the action (create), resource (AI agent), and scope (workspace). This distinguishes it from sibling tools like agents_update (update) and agents_delete (delete).

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

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

The description provides explicit best-use context for each execution mode (e.g., 'Best for: auto-replies, group monitoring, keyword-based filtering' for ai_assisted). It also gives specific advice for keyword filtering to use ai_assisted mode. However, it does not explicitly state when not to use this tool or compare to alternatives like agents_add_file.

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?

Given no annotations, the description bears full responsibility for behavioral disclosure. It explicitly warns that deletion is permanent and cannot be undone, and that all triggers will be removed, which are critical side effects. Minor omissions like return format or permissions are acceptable for a straightforward delete 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?

The description is extremely concise—two sentences with no filler. It front-loads the action and follows with a clear warning, making it easy for an agent to parse.

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

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

For a simple delete operation with a single parameter, the description covers purpose, irreversibility, and cascading deletion of triggers. It is adequate but could briefly mention the return value (e.g., success confirmation) for full completeness.

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

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

With 100% schema description coverage, the single parameter is already well-documented. The description does not add extra meaning beyond the schema's 'ID of the agent to delete,' so baseline score of 3 is appropriate.

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

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

The description clearly states 'Permanently delete an AI agent,' using a specific verb and resource. It distinguishes this tool from siblings like agents_create, agents_get, agents_update, and agents_trigger_delete, which handle different operations.

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 lacks guidance on when to use this tool versus alternatives. It does not mention prerequisites, confirmation steps, or conditions under which deletion is appropriate, leaving the agent without clear decision support.

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?

No annotations are provided, so the description must carry full burden for behavioral disclosure. It describes the return data but does not disclose behavioral traits such as permissions required, rate limits, or whether the operation is safe (non-destructive). The agent is left unaware of any side effects or access constraints.

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

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

The description is concise, with a brief introductory sentence followed by a structured bullet list. Every sentence adds value, though the list could be slightly more compact. No extraneous information.

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

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

Given the tool's simplicity (one parameter, no output schema), the description adequately explains the return value with a detailed list. However, it lacks any information about error conditions or access control, which would improve completeness. Overall, it is sufficient for a basic fetch operation.

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

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

Schema coverage is 100% and the single parameter 'agent_id' is described as 'ID of the AI agent to fetch'. The description does not add additional meaning beyond the schema, so it meets the baseline without enhancement.

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

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

The description clearly states 'Get detailed information about a specific AI agent' with a specific verb and resource. The bullet list of returned fields further clarifies the scope. Among siblings, this tool is clearly distinct as a read operation, unlike agents_create, agents_update, or agents_delete.

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

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

The description implies usage for fetching full agent details by ID but does not explicitly state when to use it versus alternatives like agents_list or agents_trace_get. There is no guidance on prerequisites or exclusions, leaving the agent to infer context.

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

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

With no annotations, the description covers the key behavioral trait: ending the turn silently. It warns that narrated silence would be sent verbatim. It does not mention any side effects or required permissions, but for a simple silent action, the transparency is sufficient.

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

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

Two sentences with no redundancy. The first sentence states the primary action, and the second provides use cases and a critical warning. Every word earns its place.

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

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

Given the tool's simplicity (one parameter, no output schema, no nested objects), the description is complete. It covers purpose, usage conditions, and parameter behavior. No missing details are apparent.

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

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

The single parameter 'reason' has a description that adds value beyond the schema: it explains the field is free-form, stored for audit in trace_tool_executions.tool_params, and that reason filters are scan-only. Schema coverage is 100%, but the extra context justifies a higher score.

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

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

The description clearly states the tool's purpose: 'End this turn without sending any message.' It specifies the verb (end) and resource (turn), and the phrase 'ONLY correct way to stay silent' distinguishes it from potentially confusing alternatives like narrated silence text.

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 usage guidance is provided: 'Use when the thread is owned by a human operator after job.escalate, when the guest is self-resolving, when the message is a duplicate, or for observation-only turns.' It also warns against using narrated silence text, making the conditions for use very clear.

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

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

No annotations are provided, so the description carries the full burden. It implies a read-only list operation but does not explicitly state no side effects. It describes the output structure, which adds some transparency.

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

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

Three sentences plus a bullet list, front-loaded with main purpose, concise and no fluff.

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

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

Covers essential aspects: what it does, what it returns, how to filter. Lacks mention of pagination or limits, but for a simple list tool it is mostly complete.

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

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

Schema description coverage is 100%. The description mentions filtering by enabled status but does not add significant meaning beyond what the schema already provides. Baseline score 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 clearly states it lists all AI agents in the workspace, specifying the returned data (basic info, trigger count, knowledge count). It distinguishes from siblings like agents_get (single agent) and agents_list_drafts (drafts).

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

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

The description provides explicit use cases: see all agents, filter by enabled/disabled status, get IDs for further operations. It does not explicitly state when not to use it, but the context is clear.

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

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

With no annotations provided, the description carries full burden. It discloses that drafts have expiration, creation time, and are unsent, but does not mention any safety or authorization needs. Given the read-only nature of listing, it is adequate.

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

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

The description is concise and well-structured: a clear purpose line, bullet points of included fields, and example queries. No fluff.

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

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

The description explains the return fields (thread info, trigger, response, creation time, expiration) well, compensating for the lack of output schema. It does not cover pagination or ordering, but is otherwise complete for a list tool.

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

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

Input schema has 100% description coverage for both parameters (limit and thread_id). The description adds no new meaning beyond what is already in the schema, so baseline score 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 clearly states 'List pending agent drafts awaiting approval' and provides example user queries. It unambiguously identifies the tool's function and distinguishes it from siblings like agents_approve_draft and agents_reject_draft.

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

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

The description explicitly says 'Use this when user asks...' and lists specific queries. It implies context for use, though it does not explicitly state when not to use it or name alternatives beyond the general 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?

Describes return fields (file_id, title, status, chunk_count) and explains that chunk_count=0 means still processing. No annotations provided, so this is valuable behavioral disclosure. Does not explicitly state read-only, but it's implied by 'list'.

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

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

Two concise sentences plus return field explanation and usage note. Front-loaded with primary function, no wasted words.

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

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

Given the tool's simplicity (one param, no output schema), the description covers purpose, scope, return fields, and related tools. It is complete for an agent to select and use 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 coverage is 100% for the single parameter agent_id, so baseline score applies. The description does not add additional meaning or context beyond the schema's description.

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

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

Clearly states it lists files attached to a specific agent, distinguishing from shared collections. The verb 'list' and resource 'files attached to this agent' are explicit and differentiate from sibling tools like collections_list_files.

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

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

Provides context that it lists agent-specific files (not shared collections) and mentions related tools for add/remove (agents.add_file, agents.remove_file). Lacks explicit when-not or alternative comparisons, but the distinction is clear enough for typical use.

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

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

The description states that 'every edit to the agent's prompt is snapshotted to an append-only table,' disclosing the immutable, append-only nature of the history. It implies read-only behavior, which is sufficient given no annotations. No mention of auth needs or rate limits, but acceptable for a browsing 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?

Two sentences, front-loaded with purpose, followed by usage guidance. Every word is meaningful; no redundancy. Efficient and clear.

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 is provided, and the description does not specify the return format (e.g., fields returned like version_number, prompt_text, timestamp). It mentions 'list past versions' but lacks details on what agents can expect, which is important for an API tool.

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

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

Schema coverage is 100% with clear parameter descriptions (agent_id, limit, before_version). The description adds minimal extra semantics beyond contextualizing the parameters as part of a browsing history. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'List past versions of an agent's `prompt_text`.' It uses a specific verb (list) and resource (past versions of prompt_text), and differentiates from the sibling tool `agents.prompt_restore` by mentioning the intended 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?

The description provides a clear use case: 'use this tool to browse history, find a prior known-good version, and copy it into `agents.prompt_restore`.' It gives context for when to use it but does not explicitly state when not to use it or list 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?

Discloses that restore creates a new version and preserves history, indicating non-destructive behavior, which is important since no annotations are provided.

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 well-structured, front-loaded sentences without any extraneous information.

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

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

Covers purpose, outcome, and prerequisite adequately for this simple restore tool, with no missing elements given the lack of output 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?

Adds context beyond the schema: explains reason parameter's purpose ('shows up in history UI') and that version_number comes from prompt_history.

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

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

The description clearly states it restores a past version of an agent's prompt_text by version_number, distinguishing it from sibling tools like agents_prompt_history 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 instructs to first use agents.prompt_history to obtain the version_number, providing clear guidance on prerequisite steps.

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

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

Discloses that the draft will be marked as rejected and won't be sent, which is basic behavioral information. However, without annotations, it lacks details on permanence, permissions, or side effects. The description is adequate for a simple action but not rich.

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

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

Description is extremely concise: two short sentences for the main function and a bullet list of use cases. No redundant information. Front-loaded with the core action.

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

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

Given no output schema and the simple nature of the tool (reject a draft), the description covers the purpose and usage adequately. Could mention what the tool returns or any confirmation, but this is not critical for a basic rejection action.

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?

Input schema has 100% coverage with descriptions for both parameters. The description does not add additional meaning or clarify usage beyond what the schema provides. 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?

Clearly states the action (reject) and resource (pending agent draft). Distinguishes itself from sibling tools like agents_approve_draft by its focus on rejection. The verb and resource are specific and unambiguous.

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

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

Provides explicit example user phrases that trigger use, such as 'Reject this draft' and 'Don't send this'. It also gives a general condition ('when the generated response isn't appropriate'). Does not mention alternatives like agents_approve_draft, but the context is clear.

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

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

The description clarifies a key behavioral trait: the file is detached, not deleted. However, with no annotations provided, it lacks details on permissions, side effects, or immediate impact on the agent's knowledge, which would make it more transparent.

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

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

The description is two sentences long, front-loads the purpose, and every sentence adds value. No unnecessary words.

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

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

For a simple detach operation, the description covers purpose, behavioral nuance, and a prerequisite. It lacks error handling or post-condition details, but these are not critical for this tool.

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

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

The input schema already has 100% description coverage for both parameters. The description adds marginal value by referencing agents.list_files for file_id, but does not provide additional semantic meaning beyond the schema.

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

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

The description clearly states the tool removes a file from an agent's private knowledge. It distinguishes itself from siblings like agents_add_file by specifying detachment rather than deletion, and references agents.list_files for finding the file_id.

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 provides a direct usage hint to use agents.list_files to obtain the file_id. While it does not explicitly state when not to use this tool, the context of removing a file is straightforward and the sibling tools (add, list) make the usage clear.

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

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

No annotations provided, so description carries full burden. It thoroughly explains that send_mode is forced to 'draft', no real message is sent, no idempotency key is written, and routing uses production logic. It also details both hit and miss return structures, including skip reason and simulator_warnings.

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

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

Description is well-structured with a front-loaded purpose paragraph, followed by usage guidance and return details. While it contains many details, each sentence serves a purpose. Slightly lengthy but justified by complexity.

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

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

Given no output schema, description provides full return structures for both hit and miss. It covers edge cases (skip reason, warnings) and multiple simulation types. For a 4-parameter simulation tool, this is exceptionally 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%, baseline 3. Description adds value by explaining thread_id must belong to workspace, message_text default, blockchain_tx_data expected keys, and attachment_file_ids shape/usage (e.g., for logos or documents). This meaningfully extends the schema.

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

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

The description clearly states the tool replays an inbound message through the real trigger pipeline to test routing. It distinguishes itself by forcing 'draft' mode (no real send) and mentions two simulation types (message_text or blockchain_tx_data). No sibling tool duplicates this functionality.

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 'Use to verify routing for a thread' and mentions when no match returns skip reason. Does not explicitly state when not to use it, but the context (simulation vs real send) is implied. Could be improved by naming alternatives like agents_ask or actual send 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?

No annotations provided, so description must carry burden. It states it 'reports completion' but doesn't disclose side effects, idempotency, or return behavior. Minimal transparency, but acceptable for a simple reporting 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?

Two concise sentences with no redundant information. Front-loaded with action and resource.

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

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

For a simple tool with 3 params, no output schema, and clear purpose, the description is adequate. Could mention if it is a one-way notification, but not critical.

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 baseline is 3. Description adds no extra context beyond what the schema already provides for each parameter.

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

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

The description states 'Report that a Claude Code agent task has been completed' – clear verb and resource. It distinguishes from sibling tools like agents_create or agents_get by focusing on completion reporting.

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 'Call this when you finish processing an agent_task from DialogBrain' – clear when to use. Does not mention when not to use or alternatives, but context is sufficient.

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

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

With no annotations, description carries full burden and excels: discloses default stripping of LLM bodies, that include_llm_bodies=true emits WARNING audit log, full=true disables truncation, and failed LLM completion_text is always returned (capped). Also mentions agent_id mismatch returns not_found.

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

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

Four sentences, no redundancy. First sentence defines purpose, second gives usage, third explains defaults and flags with side effects. Efficient and well-organized.

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

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

Given no output schema, description doesn't fully explain return structure beyond mentioning error_message and completion_text. But it covers key behavioral aspects and parameter details. Lacks full return format, which would aid agent understanding.

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

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

Schema coverage is 100% (baseline 3). Description adds value: for include_llm_bodies, adds 'when diagnosing prompt engineering issues'; for full, adds 'Escape hatch for a human operator'; for trace_id, specifies it comes from agents_traces_list; for agent_id, notes 'scope validation'. Adds behavioral context beyond schema.

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

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

Description clearly states verb 'Fetch' and resource 'full execution detail for a single trace', enumerating contents like tool executions, events timeline, LLM call spans with error_message. Distinguishes from sibling agents_traces_list by specifying it gets one trace's details.

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 advises to use after agents_traces_list identifies a trace of interest (failed, slow, unexpected). Provides context for when to use include_llm_bodies and full flags. No explicit exclusions or alternatives, but context is clear.

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

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

With no annotations, the description fully discloses behavior: pagination edge case (returned_count=0, has_more=true when rows deduplicate), known upstream bug (source='agent' also matches voice), and filter details (comma-separated values, ISO-8601 dates).

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

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

The description is well-organized: first sentence states purpose and scope, then usage scenarios, then filter details, then return fields and edge cases. Every sentence adds value; no fluff or 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?

Given no annotations and no output schema, the description comprehensively covers filters, pagination behavior, edge cases, and known bugs. It explains return fields adequately for the tool's purpose without overloading.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra context: explains filter usage (e.g., comma-separated source values, ISO-8601 format for dates), pagination parameters (limit/offset), and the meaning of return fields (returned_count, dropped_on_page, has_more). This goes beyond the schema descriptions.

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

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

The description clearly states it lists recent execution traces for an agent, scoped to one agent, and explains it is the same data as /admin/requests, readable by an LLM. It distinguishes from siblings like agents.trace_get and agents_traces_stats by specifying use cases and pairing recommendations.

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 states when to use the tool (e.g., agent call timed out, wrong draft, latency debugging) and recommends pairing with agents.trace_get. While it does not explicitly list when not to use it, the context is clear and practical.

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?

No annotations provided, but the description adds behavioral context: days capped at 30 due to ClickHouse TTL, exact match on agent_id. It implies read-only statistics but doesn't explicitly state permissions or side-effects, which is a minor 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?

Two sentences: first lists all statistics offered, second provides usage guidance and constraints. No redundant words, clearly 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?

Given no output schema, the description lists the statistics but doesn't detail the exact structure (e.g., histogram format, error breakdown keys). However, it is reasonably complete for a stats tool, especially with the TTL and scoping details.

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 covers 100% of parameters. The description adds value beyond schema: 'exact match, no substring bleed' for agent_id and 'capped at 30 — matches ClickHouse request_traces TTL' for days.

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

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

The description clearly states it provides aggregated trace statistics (total runs, success rate, avg duration, error breakdown, top tools, histogram) for one agent, distinguishing it from sibling trace tools by framing it as a bird's-eye view.

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 to use this for a bird's-eye view before diving into individual traces with agents_traces_list/agents_trace_get, and notes the exact match scoping and 30-day cap due to TTL.

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 no annotations, the description carries full behavioral disclosure burden. It explains trigger types and condition semantics in detail, including how fields like keyword_match and channel_types work. However, it does not mention side effects (e.g., immediate activation, dependencies on agent state) or the response structure.

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

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

The description is well-structured with a clear header, bullet points for trigger types, and a detailed conditions section. It is front-loaded with the main purpose. However, the conditions section is lengthy and could be more compact.

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

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

Given the tool's complexity (7 parameters, nested conditions), the description covers the main functionality and condition details. However, it omits the return value (e.g., created trigger details) and does not mention prerequisites beyond the schema's required fields.

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

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

Schema coverage is 100%, but the description adds significant value by explaining the conditions object in depth, including supported fields, defaults, and usage guidelines (e.g., for voice channels and AI filters). This far exceeds the schema's brief description.

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

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

Clearly states 'Create a new trigger for an AI agent' and lists trigger types and their purposes. The verb 'create' is specific, and the resource 'trigger' is well-defined, distinguishing it from sibling tools like agents_trigger_update or agents_trigger_delete.

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

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

Provides clear context on what the tool does and the types of triggers, but does not explicitly state when to use it over alternatives (e.g., updating an existing trigger). No 'when not to use' or alternative recommendations are given.

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 no annotations, the description carries the burden. It correctly warns that deletion is irreversible, which is critical for a destructive operation. However, it does not disclose prerequisites, side effects, or return behavior.

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

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

The description is extremely concise with two sentences. The action is front-loaded, and the warning follows directly. No unnecessary 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 delete tool with two parameters and no output schema, the description covers the essential purpose and a key behavioral aspect (irreversibility). It could mention the return value or confirmation, but overall it is sufficiently 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?

The input schema already provides clear descriptions for both parameters (agent_id and trigger_id). The description adds no additional meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the action: 'Delete a trigger from an AI agent.' Uses a specific verb and resource, and distinguishes from sibling tools like agents_trigger_create and agents_trigger_update.

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

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

There is no guidance on when to use this tool versus alternatives. A warning about irreversibility is given, but no mention of when to prefer this over other actions (e.g., disabling a trigger).

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?

No annotations are provided, so the description must carry full burden. It only states update and partial update behavior, omitting details on idempotency, side effects (e.g., conditions replacement), authorization needs, or error handling.

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

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

Two sentences with clear purpose and key usage note. No fluff, front-loaded, and well-structured.

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

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

For a mutation tool with 8 parameters (including nested objects) and no output schema, the description is adequate but incomplete. It does not specify return values or behavior on failure, which would aid an agent.

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

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

Schema coverage is 100%, baseline 3. The description adds value by clarifying that only provided fields are updated, which goes beyond the schema's individual parameter descriptions.

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

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

The description clearly states 'Update an existing AI agent trigger,' specifying the action and resource. It is distinct from sibling tools like agents_trigger_create and agents_trigger_delete.

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

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

The description notes that all parameters are optional, implying partial updates, but does not explicitly contrast with create or delete, nor does it provide when-not-to-use 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?

No annotations provided, so the description carries full burden. It is highly transparent, noting that all parameters are optional and only provided fields are updated, and includes warnings for destructive actions like prompt_text replacement.

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

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

The description is well-structured with a clear opening sentence and bulleted list of use cases. It is appropriately sized for a complex tool with 43 parameters, with no wasted words.

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

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

Given the tool's complexity and lack of output schema, the description is highly complete, covering all update scenarios and parameter behaviors. It effectively compensates for missing 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%, so baseline is 3. The description adds value by grouping use cases and explaining parameter intent (e.g., priority explanation), going beyond the schema's per-parameter descriptions.

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

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

The description clearly states 'Update an existing AI agent's configuration.' It provides a specific verb ('Update') and resource ('AI agent'), distinguishing it from siblings like agents_create or agents_delete.

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

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

The description lists many use cases with bullet points, providing clear context on when to use the tool. However, it does not explicitly mention when not to use it or compare with alternatives, though the sibling list offers implicit differentiation.

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?

Since no annotations are provided, the description carries the full burden. It discloses that the tool calls the Voyage AI embedding API to generate the reference vector, which is valuable. However, it does not mention potential side effects (e.g., cost, rate limits, authentication needs, or what happens on failure). The threshold behavior is well explained, but details about the creation process (e.g., immediate activation) are missing.

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

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

The description is well-structured: a concise summary, then technology explanation, usage tips, threshold guidance, and a note about the external API call. It is informative without being overly verbose. A slight trimming of some sentences could improve conciseness, but overall it is efficient for the tool's complexity.

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

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

Given the tool has three parameters (all well-documented in schema) and no output schema, the description covers purpose, mechanism, parameter importance, and external API dependency. However, it does not explain the return value (likely a filter identifier) or state whether creation is asynchronous or synchronous. Prerequisites (e.g., API key) are not mentioned. For a creation tool, it is fairly complete but leaves some gaps.

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

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

The schema already describes all three parameters (name, threshold, description) with 100% coverage. The description adds significant value by stressing the importance of the description field, providing concrete examples, and explaining threshold values and their impact. This goes beyond the schema and helps the agent craft proper inputs.

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

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

The description clearly states the tool's purpose: creating an AI filter for semantic intent-based message matching. It explains the underlying technology (vector embeddings via Voyage AI) and how the filter works (embedding description as reference vector, cosine similarity comparison). This distinguishes it from sibling tools like ai_filters_list, ai_filters_update, which have different operations.

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 good usage guidance: it explains when to create a filter, emphasizes the importance of the description field with examples, and advises on threshold tuning (0.5 default, lower for wider net, higher for precision). However, it does not explicitly state when not to use it or compare to alternatives like ai_filters_test or ai_filters_update, which would improve clarity.

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 no annotations, the description carries the full burden. It clearly states the action is permanent ('cannot be undone') and warns about triggers that reference the filter by ID no longer matching, disclosing important side effects.

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

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

The description is very concise with two short paragraphs, front-loading the purpose and then providing necessary warnings. Every sentence adds value with no redundancy.

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

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

For a simple delete operation with one required parameter and no output schema, the description is complete. It covers the action, irreversibility, and impact on triggers, which is sufficient context.

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

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

The input schema already has a description for 'filter_id' as 'ID of the filter to delete,' achieving 100% coverage. The description adds no further parameter details, so a baseline score of 3 is appropriate.

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

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

The description starts with 'Permanently delete an AI filter,' which uses a specific verb and resource, clearly distinguishing it from sibling tools like create, list, or update.

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

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

The description explicitly states 'When to use: - User wants to remove a filter they no longer need,' giving clear context for usage. It does not provide explicit when-not-to-use or alternative tools, but the context is sufficient.

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

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

Since no annotations are provided, the description carries full burden. It correctly implies a read-only operation ('list all'), explains the embedding-based matching mechanics, and specifies the return fields. It could mention potential limitations like pagination but is transparent overall.

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

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

The description is well-structured with a clear purpose, technical explanation, usage guidance, and return value specification. Every sentence is informative and non-redundant. It is concise yet comprehensive.

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

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

Given no output schema, the description fully explains the return fields (id, name, description, threshold, is_active). It provides sufficient context about the tool's role within the AI filtering system, making it complete for an agent to understand and use.

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

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

The input schema has zero parameters, and schema coverage is 100%. Per the guidelines, 0 parameters baseline is 4. The description adds context about what the tool returns and how filters work, but no parameter documentation is needed.

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 clearly states the tool lists AI filters for the workspace. It then explains what AI filters are (semantic/intent-based) and how they differ from keyword filters, making the tool's purpose specific and distinct.

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

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

The 'When to use' section explicitly lists three concrete scenarios: checking existing filters before creation, getting IDs for triggers, and reviewing thresholds/active status. This provides strong guidance for when this tool is appropriate versus sibling tools like ai_filters_create.

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 no annotations, the description fully bears the responsibility of disclosing behavior. It reveals that the tool calls the Voyage AI embedding API, computes cosine similarity, and returns similarity score, match boolean, and threshold. It does not mention rate limits, authentication needs, or potential side effects, but as a read-only test tool, the disclosed information is sufficient.

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

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

The description is concise: four sentences, a bulleted list, and a return format specification. It is front-loaded with the core purpose and efficiently organized, with no extraneous information.

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

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

Given the absence of an output schema, the description provides the return format and explains the entire testing process. It covers the tool's scope adequately. Minor omissions like error handling or prerequisite (filter must exist) are not critical for a well-defined test tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds technical context for the 'message' parameter (embedding and comparison), but the schema already describes both parameters adequately. The added value is marginal, not enough to raise the score above baseline.

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

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

The description clearly states the tool tests a message against an AI filter to check for a match, explains the embedding and cosine similarity process, and uses specific verb+resource ('test message against filter'). It distinguishes itself from sibling tools like ai_filters_create by focusing on testing rather than CRUD operations.

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 three specific use cases: verify filter, tune threshold, debug. However, it lacks explicit guidance on when not to use this tool (e.g., for creating or updating filters) and does not compare it to sibling testing-like tools such as agents_simulate_inbound. Nevertheless, the listed use cases offer clear context for invocation.

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

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

The description discloses a key behavioral trait: changing the description calls the Voyage AI embedding API to re-generate the reference vector. With no annotations provided, this adds important context. It does not mention other potential side effects or prerequisites, but the mutation is clearly stated.

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

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

The description is extremely concise and well-structured: a single opening sentence followed by bullet-point use cases and a note. Every sentence adds value 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 partial-update tool with no output schema and no annotations, the description covers the purpose, usage scenarios, and a key side effect (API call). It is sufficiently complete for an agent to understand when and how to use the tool.

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

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

The input schema has 100% description coverage for all parameters. The description summarizes the fields but does not add meaning beyond what the schema already provides (e.g., ranges, optionality). Hence, it meets the baseline of 3.

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

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

The description clearly states the verb 'Update' and the resource 'AI filter', and lists the specific attributes (name, description, threshold, active state). It distinguishes from sibling tools like create, delete, list, and test.

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

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

The 'When to use' section provides explicit scenarios (rename, refine description, adjust threshold, enable/disable). It also notes that at least one field must be provided. However, it does not mention when not to use or suggest alternatives, which keeps it from a perfect score.

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

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

No annotations provided, so description carries full burden. Discloses that already-applied tags get updated to is_manual=true, but lacks details on error handling, permissions, or side effects.

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?

Concise at 5 lines with front-loaded action and clear structure. No superfluous 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?

No output schema, but tool is simple with two required parameters. Description covers action and a key behavioral detail. Adequate for its complexity, though missing potential error scenarios.

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 description adds minimal value. Repeats parameter names and types. Constraint of 1-20 IDs is already in schema description.

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

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

Clearly states 'Apply one or more AI tags to a thread (manually)' with specific verb and resource. Distinguishes from siblings like ai_tags_remove_from_thread.

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 'When to use:' section with two scenarios. Does not explicitly state when not to use or mention alternatives, but effectively guides usage.

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

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

No annotations provided, so the description carries the full burden. It discloses that AI tags are lightweight classifiers that run on every incoming message, that labels are applied automatically, and mentions limits (20 personal/50 team). Does not mention immediate activation or side effects, but the creation action is straightforward.

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

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

The description is well-structured: starts with a one-liner, then explains the concept, provides usage guidance, tips, and limits. It is front-loaded with the main action and every sentence adds unique value without being verbose.

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

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

Given the tool's simplicity (4 parameters, no output schema), the description adequately covers purpose, usage, and parameter tips. It lacks explicit return value information, but for a creation tool, the behavior is clear enough for an AI agent to invoke correctly.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds value by explaining the 'description' parameter as a classifier prompt with tips and examples, going beyond the schema. Icon and color parameters are not elaborated beyond schema, but the overall parameter information is clear.

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 starts with 'Create a new AI tag (automatic message filter)', clearly stating the verb and resource. It explains what AI tags are and distinguishes from sibling tools like ai_tags_delete, ai_tags_list, and ai_filters_create by emphasizing auto-classification of incoming messages to pre-filter threads.

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

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

Includes a 'When to use' section explicitly stating two use cases: auto-classifying incoming messages and reducing AI agent costs. Provides tips for the description field but lacks explicit when-not-to-use or alternative tools, though the context implies this is for lightweight classification rather than complex filtering.

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?

Without annotations, the description fully discloses key behaviors: automatic removal of thread associations, irreversibility, and that threads are not deleted. This meets the full burden for transparency.

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

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

Extremely concise: three short sentences effectively convey purpose, usage context, and behavioral notes. No filler, every sentence adds value.

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

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

Given the simple tool (1 param, no output schema) and full schema coverage, the description adequately covers purpose and side effects. Slight lack of return value info, but not critical for a delete operation.

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% (tag_id described as 'ID of the tag to delete'). The description adds no additional context about the parameter, so baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Delete a personal AI tag') and resource (tag). It distinguishes itself from sibling tools like ai_tags_add_to_thread and ai_tags_create by specifying deletion.

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 'When to use' context ('user wants to permanently remove a tag'), but lacks explicit alternatives or when-not-to-use guidance. The behavioral notes (automatic thread association removal, irreversibility) help, but no direct comparison with sibling tools.

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

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

Given no annotations, the description fully explains behavior: lightweight classifier runs on every incoming message, tags are applied automatically, and it returns thread counts. No contradictions.

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

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

Well-structured with separate sections, front-loaded with the main action. A few sentences could be trimmed, but overall efficient and clear.

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, but description explains return values (tags with thread counts) and provides sufficient context about the AI tags feature, making it complete for a list tool.

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

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

Input schema has zero parameters, so schema coverage is 100%. Description adds value by explaining the return data (tags with thread counts) and the broader context of the system.

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

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

Description clearly states 'List all personal AI tags' and explains the purpose of AI tags as automatic message filters, distinguishing it from sibling tools like ai_tags_create or ai_tags_delete.

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

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

Provides explicit 'When to use' bullets: check filters before creating, get tag IDs for add/remove, and see thread counts. Lacks explicit when-not-to-use but is clear in context.

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

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

With no annotations, the description must bear the burden. It states the core behavior but does not disclose side effects, permissions, or error conditions. It is adequate for a simple removal but lacks detail.

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

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

The description is very concise, with a clear structure: main action followed by a bulleted 'When to use' list. No unnecessary words.

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

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

For a simple removal tool, the description covers purpose, usage context, and inputs. Lacks mention of return behavior or error cases, but overall sufficient given the simplicity.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds no extra meaning beyond the schema, only reinforcing the need for both IDs. 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?

The description clearly states the action ('Remove') and the resource ('a specific AI tag from a thread'). It distinguishes from sibling tools like ai_tags_add_to_thread (opposite) and ai_tags_delete (deletes tag definition, not association).

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

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

The 'When to use' section provides explicit contexts: un-labeling or correcting tags. It requires both IDs. However, it does not mention when not to use or direct to alternatives like ai_tags_delete for deleting the tag entirely.

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?

No annotations are provided, so the description carries the full burden. It states the tool updates tags and lists fields, implying partial update. But it lacks details on side effects, error conditions, permissions, or what happens if tag_id is invalid. Basic behavior is clear but incomplete.

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

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

The description is concise with two clear paragraphs. The first states the action and updatable fields, the second provides usage scenarios. No superfluous words; structure is 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?

Given no output schema, the description adequately covers purpose and usage. It explains partial updates and required fields. However, it could mention that tag_id must be obtained from ai_tags_list or similar, but overall it is fairly complete for an update tool.

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

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

Schema descriptions cover all parameters (100% coverage). The description adds value by grouping fields and emphasizing partial update ('Provide only the fields you want to change'), which reinforces the optional nature beyond the schema alone.

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

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

The description explicitly states the tool updates a personal AI tag's name, description, icon, color, or active state. It lists specific use cases, clearly distinguishing it from siblings like ai_tags_create (create) and ai_tags_delete (delete).

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

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

The description provides a clear 'When to use' list covering rename, change icon/color/description, and enable/disable. It notes that only fields to change should be provided and at least one field is required. However, it does not explicitly exclude scenarios or mention alternatives.

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

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

No annotations provided, so description carries burden. Describes basic behavior (shows busy/free) and hints at filtering via parameters, but lacks details on timezone handling, error states, or output structure.

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 purpose. No unnecessary words. Highly 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?

No output schema is provided, and the description does not specify the format of returned data (e.g., list of time blocks, objects with start/end). This is a significant gap for a tool with 5 optional parameters.

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

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

All 5 parameters have descriptions in schema, so description adds no additional meaning. Baseline score of 3 is appropriate.

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

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

Clearly states it checks free time in Google Calendar, showing busy periods and free slots. Distinguishes from sibling calendar tools like calendar_list_events by focusing on availability.

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 'Useful for finding meeting times or checking schedule conflicts', providing clear use context. However, no explicit alternative suggestions or when-not-to-use 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?

No annotations are provided, so the description carries full burden. It discloses that events are created and provides date format requirements, but does not mention side effects (e.g., whether attendees are notified), required permissions, error behavior, or what happens on success (return value). This leaves significant behavioral gaps.

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 three short sentences, front-loaded with purpose. It is concise with no fluff, but could be slightly more structured (e.g., grouping core vs optional parameters). Reasonably 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?

Given 13 parameters and no output schema or annotations, the description is overly minimal. It lacks details on many parameters, does not mention default behaviors (e.g., calendar_id defaults to primary), and omits information about the return value. There is a contradiction: description implies title, start, end are required, but schema has no required fields.

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

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

Schema coverage is 100%, so baseline is 3. The description repeats schema content for core parameters (title, start, end) but adds no meaning beyond what the schema already provides. It does not elaborate on many other parameters (location, timezone, conference_data, etc.).

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

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

The description clearly states 'Create a new event in Google Calendar', which is a specific verb+resource. It distinguishes this tool from sibling calendar tools like calendar_update_event or calendar_list_events, as creation is explicitly mentioned.

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 for creating events but does not provide explicit guidance on when to use this tool versus alternatives like calendar_update_event or calendar_check_availability. No exclusion criteria or prerequisites are mentioned.

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

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

No annotations exist, so the description must carry the full burden. It only states 'This action cannot be undone', which is critical, but omits other behavioral details such as required permissions, side effects on attendees (partially covered by schema parameter), or response behavior. This is insufficient for a destructive operation.

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 concise sentences (15 words) that front-load the primary action and critical warning. Every word earns its place without unnecessary fluff.

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

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

With no output schema and three parameters, the description does not explain return values, error behavior, or confirmation. For a delete tool, a simple success indication would be useful, and the description lacks this completeness.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond what is already in the schema parameters, resulting in no extra value.

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

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

The description clearly states the action ('Delete an event') and the resource ('Google Calendar'), distinguishing it from sibling tools like calendar_create_event and calendar_update_event.

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 explicit when-to-use or alternatives are provided. The warning 'Use with caution' implies caution but does not guide the agent on when to prefer this tool over others. Since delete operations are straightforward, this is adequate but not exemplary.

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 no annotations, the description partially discloses behavior (default upcoming events, filtering capabilities). However, it omits details like pagination, rate limits, or error handling. It is adequate but not exhaustive.

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 concise sentences with no redundancy. It front-loads the core action and then adds key default and filter information efficiently.

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 5 parameters, no output schema, and no annotations, the description covers the main purpose and defaults. It lacks details on return format, timezone handling, or edge cases, but is sufficient for a straightforward list tool.

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

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

Schema description coverage is 100%, so the descriptions already document each parameter's purpose. The tool description adds minimal extra value beyond confirming defaults and filtering, so a baseline score of 3 is appropriate.

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

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

The description explicitly states the verb 'list' and resource 'events from Google Calendar', clearly distinguishing it from sibling tools like create, delete, update, and check availability. It also notes default behavior and filtering options.

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 for viewing events with optional date range and search filters. It does not explicitly state when not to use or provide alternatives, but the context is clear enough for an agent to infer appropriate use cases.

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

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

With no annotations provided, the description carries the full burden. It discloses partial update behavior but lacks details on permissions required, error handling (e.g., event not found), or side effects beyond updating fields.

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

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

Two concise sentences, front-loaded with purpose and supported by a list of modifiable fields. No unnecessary words.

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

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

The description is minimally adequate for a simple CRUD tool but lacks details on required parameters (event_id implicit), default calendar_id, and return behavior. No output schema exists to compensate.

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 each parameter is documented. The description adds minimal value by categorizing fields, but the partial update hint is useful. Baseline score is appropriate.

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

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

The description clearly states the action (update an existing event) and the resource (Google Calendar event). It lists modifiable fields, distinguishing it from sibling tools like create and delete.

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

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

The description implies partial update semantics with 'Only specified fields will be updated,' but does not explicitly state when to use this tool versus alternatives, nor does it mention prerequisites or 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?

With no annotations, the description fully covers behavior: it returns transcript rows, call status, duration, outcome, and notes that answered_at is null until pickup. It also mentions behavior for active calls.

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

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

The description is concise, with the purpose stated in the first sentence. No extraneous information, every sentence adds value.

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

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

For a tool with one parameter and no output schema, the description adequately explains the return structure and special conditions (answered_at, active calls). It is sufficiently complete for an agent to use correctly.

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

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

Schema coverage is 100% with a clear description for call_id. The tool description does not add extra semantic detail beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool retrieves structured transcript and final state of a voice call by call_id, listing specific return fields (per-turn rows, status, duration, outcome). This is distinct from sibling tools like calls_make or calls_list_active.

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 mentions the call_id comes from calls.make, providing context on when to use this tool. Though it doesn't explicitly state when not to use it, the purpose is clear enough for differentiation among 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?

No annotations are provided, so the description carries the burden. It discloses idempotency and implies a write operation. However, it does not mention permissions, side effects on the call session, or success/error details beyond idempotency.

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 concise sentences covering purpose, usage, and idempotency. No wasted words; every sentence adds value.

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

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

For a simple hangup tool with no output schema and minimal parameters, the description covers the core context: when to use it, idempotency, and parameter sources. Lacks error behavior details but is largely 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 coverage is 100% and the schema already describes both parameters well (call_id source, reason metadata storage). The description adds no substantial new meaning beyond the schema, 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 clearly states the action ('Hang up'), the resource ('active voice call'), and the identifier ('by call_id'). It distinguishes from siblings like calls_make and calls_list_active by its specific termination function.

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

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

Explicitly states when to use: 'after calls.make when the agent decides to terminate before the callee does, or to abort a stuck call.' Also notes idempotent behavior. No exclusionary guidance, but sufficient for 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?

With no annotations, the description carries the full burden. It indicates a read operation (listing active calls) and hints at the purpose (line check), but does not disclose details like return format, side effects, or permissions. This provides minimal beyond purpose.

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

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

Two concise sentences: first sentence states purpose, second provides usage context. No redundant information, efficiently packed.

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

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

The tool has no output schema and only 2 optional parameters. Description covers when to use but fails to explain the return format or structure of the list. Given low complexity, it is adequate but not fully complete.

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

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

Schema coverage is 100%, with both parameters described. The description adds no additional meaning beyond the schema, only hinting at Telegram context. Baseline 3 is appropriate as 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 clearly states the tool lists active voice calls in the workspace, using a specific verb and resource. It distinguishes from sibling tools like calls_make or calls_hangup by focusing on listing, and the context confirms no direct sibling exists for generic call listing.

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

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

Explicitly tells when to use: before calls.make on a Telegram account to check line availability. This provides clear context for usage and implies a prerequisite (one call per account), giving strong 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?

With no annotations, the description carries full burden. It discloses that the tool returns one row per call (not per turn), the specific fields returned, and behavioral details for several parameters (e.g., thread_id back-links, participant_name substring match via parent group roster, mutual exclusivity of contact_id and participant_name). It does not mention pagination or default limit behavior, but covers many key aspects.

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 fairly long but every sentence adds substantial value. It is front-loaded with the main purpose and then provides structured details. There is no redundancy or fluff. Could be slightly tighter, but overall effective.

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

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

Given no output schema, the description includes the return fields. It also references pairing with another tool for transcripts. It covers many edge cases through parameter descriptions. However, it does not address pagination, sorting, or error conditions, which would make it even more complete for a tool with 8 parameters.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value beyond schema: it explains default values for `since` and `until`, timezone handling for naive timestamps, the distinction between `source` and `channel`, the back-link behavior for `thread_id`, and the mutual exclusivity and resolution logic for `contact_id` and `participant_name`. This goes well beyond the basic schema descriptions.

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

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

The description clearly states the tool searches historical voice calls by participant name, contact_id, thread, channel, source, and date range. It specifies the return format (one row per call with specific fields) and distinguishes itself from sibling tools like `messages_read_history`.

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

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

The description provides clear guidance: use this instead of `messages_read_history` for cross-thread call queries, and pair with `calls_get_transcript` for full transcripts. It explains when group calls and Meet sessions live on sub-threads, implying appropriate use cases. However, it does not explicitly state when NOT to use (e.g., for active calls).

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?

No annotations are provided, so the description carries the full burden. It explains that transcript is always stored, the re-invoke behavior via report_back, and that prior interaction is needed for Telegram calls. However, it does not mention cost implications or explicit side effects like call recording, leaving some behavioral gaps.

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

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

The description is front-loaded with the core purpose and usage guidelines. It is concise relative to the complexity of the tool but could be slightly shorter by reducing redundancy with schema descriptions. Overall, it is well-structured and informative.

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

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

Given the tool's complexity (8 parameters, two channels, no output schema), the description covers the main points: when to use, channel requirements, post-call behavior, and default settings. It could mention error handling or call duration, but it is largely complete for the agent to invoke 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?

The input schema has 100% description coverage, so the baseline is 3. The tool description adds context beyond the schema by explaining the overall flow, default channel, and the requirement for prior Telegram interaction. This adds semantic value, justifying a 4.

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

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

The description clearly states it places outbound audio/voice calls via Twilio or Telegram. It specifies the verb 'Place', the resource 'outbound AUDIO/VOICE phone call', and distinguishes from messages.send. It also mentions the agents it uses, providing a specific and clear purpose.

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

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

The description explicitly says when to use (user asks to call, ring, phone, dial, spoken conversation) and when not (do not use messages.send). It also gives context about defaults and requirements, such as channel-specific parameters, making it easy for the agent to decide when this tool is appropriate.

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 no annotations, the description fully discloses blocking behavior, timeout handling, return of ended flag and outcome, and the underlying nginx limit. No hidden behaviors.

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, no extraneous words. Every sentence adds critical 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?

No output schema, but the description adequately explains return values (ended flag, outcome, final state) and polling semantics. Covers timeout handling and system constraints. Complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds significant value: specifies call_id source (_meta.call_id), default timeout 90, cap 110, and behavior on expiry (ended=False with status='active'). Deepens understanding beyond schema.

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

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

The description clearly states the tool blocks until a voice call ends or timeout elapses, with specific verb 'block' and resource 'voice call'. It distinguishes from siblings like calls_hangup or calls_get_transcript by focusing on waiting/polling behavior.

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 when to use (after a call is made to wait for completion), what to do on timeout (re-issue), and mentions default/cap. It lacks explicit exclusions or alternatives, but the polling pattern is clear.

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

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

No annotations provided, so description carries full burden. Discloses the re-enable behavior and implies mutation. Lacks details on permissions or side effects but is sufficient for a simple add.

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

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

Two sentences with no fluff. Front-loaded with main action, followed by prerequisite and nuance. Efficient and clear.

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

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

No output schema and description does not mention return value. For a simple add tool, it is adequate but could be more complete by indicating what the response will be.

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?

Input schema has 100% coverage with descriptions. The description does not add additional meaning beyond the schema, 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 clearly states 'Add a file to a knowledge collection.' It provides a specific verb (add) and resource (knowledge collection), and differentiates from siblings like collections_remove_file.

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

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

Explicitly mentions prerequisites (file must be uploaded and indexed) and a behavioral nuance (re-enables removed files). While it doesn't explicitly state when not to use, the context is clear and helpful.

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?

No annotations exist, and the description fails to disclose whether the assignment is additive or overwriting, any prerequisites (e.g., agent must exist), or potential errors. The burden is on the description, but it only states the positive effect.

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: one for purpose, one for consequence. No redundant words.

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

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

For a simple assignment tool with two required ID parameters and no output schema, the description covers the main outcome and effect on agent behavior. Lacks mention of reversibility, but sibling tool exists for 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 coverage is 100% with clear parameter descriptions. The description adds no extra meaning beyond what the schema already provides.

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

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

The description clearly states 'Assign a knowledge collection to an AI agent' with a specific verb and resource, and distinguishes from its sibling 'collections_unassign_agent'.

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 context on the effect (scopes RAG search) and implies use for setting agent knowledge, but does not explicitly state when not to use or mention alternatives.

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

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

No annotations are provided, so the description carries the full burden. It fails to disclose behavioral traits such as idempotency, error handling (e.g., duplicate name), or required permissions. The description only states the action without any behavioral context beyond the basic operation.

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

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

The description is extremely concise at two sentences, with the core action in the first sentence and context/next steps in the second. Every sentence adds value without redundancy.

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

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

For a simple tool with 2 parameters and no output schema, the description provides enough context: what a collection is, its purpose (RAG search), and the workflow after creation. However, it lacks any mention of potential errors or behavior under failure, which would make it more complete.

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

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

Schema coverage is 100% (both parameters have descriptions). The description does not add any additional meaning beyond what is already in the schema. The constraint 'must be unique per user' for name is already in the schema's description. Baseline 3 is appropriate as the schema fully documents the parameters.

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

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

The description clearly states 'Create a named knowledge collection' with a specific verb and resource. It explains the purpose of collections (for RAG search) and distinguishes from sibling tools like collections_add_file and collections_assign_agent by mentioning them 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 description provides a clear context: create a collection, then use collections.add_file and collections.assign_agent for subsequent steps. It implicitly guides when to use this tool (when a new collection is needed) but does not explicitly state when not to use it or provide alternative tools for other scenarios.

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

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

Discloses that deleting a collection may be blocked if assigned, and force=true overrides. No annotation provided so description carries burden; could mention irreversibility or required permissions.

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 efficient sentences. First sentence states purpose, second adds critical usage condition. No wasted words.

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

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

Adequate for a delete tool but lacks details on return values, idempotency, or permissions. Without annotations or output schema, more completeness would help.

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. Description adds context for force parameter but introduces ambiguous 'CASCADE' not in schema. Slightly confuses but mostly clarifies.

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

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

Clearly states 'Delete a knowledge collection,' using a specific verb and resource. Distinguishes from sibling tools like collections_create and collections_list.

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

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

Provides guidance on when to use force=true (when assigned). Implicitly indicates default behavior (cannot delete if in use). Lacks explicit mention of alternatives like unassigning first.

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 no annotations, the description adds value by disclosing that auto-created collections are hidden by default. It lacks permissions or side-effect details but is sufficient for a read-only list 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?

The description is extremely concise with two sentences, front-loading the main action and avoiding any unnecessary words or fluff.

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

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

Given the simplicity of the tool (one boolean parameter, no output schema), the description fully covers the necessary context: what the tool does, the default behavior, and what collections are.

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 adds 'auto-created collections hidden by default' context but does not significantly enhance parameter meaning beyond the schema.

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

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

The description clearly and specifically states the tool lists knowledge collections, defines what collections are, and notes that auto-created ones are hidden by default, distinguishing it from 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?

The description provides clear context by explaining the purpose and default behavior, but does not explicitly mention when to use this tool versus alternatives like collections_list_files.

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?

No annotations are provided, so the description must fully disclose behavior. It mentions the output includes indexing status and chunk counts, but does not state whether the tool is read-only, requires specific permissions, has pagination, or any rate limits. The lack of such details is a significant gap for a tool with no annotations.

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

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

The description is two sentences long, front-loaded with the main purpose, and contains no unnecessary words. Every sentence provides value: the first states the core function, the second adds practical usage information.

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

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

Given that there is no output schema, the description should elaborate on the return structure. It only mentions 'indexing status and chunk counts' and hints at the file_id usage. This is adequate but lacks details about the shape of the response (e.g., array of objects with specific fields), leaving some ambiguity.

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

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

The only parameter, collection_id, is already described in the schema as 'ID of the collection'. The description adds no additional meaning beyond that. Since schema coverage is 100%, 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 clearly states it lists files in a knowledge collection with indexing status and chunk counts, and distinguishes from siblings like collections_add_file or collections_list. It also mentions the file_id field and how it can be used with messages.send or files.read, adding specific value.

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 when to use the tool (listing files in a collection) but provides no explicit guidance on when not to use it or alternatives. Sibling tools like collections_list or files_read are not mentioned as alternatives, leaving the agent to infer usage context.

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

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

The description discloses that the file is not deleted, only membership is removed. However, without annotations, it could provide more, such as permissions or side effects (e.g., what happens if file is in no collection).

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

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

Two sentences, front-loaded with the action. Every word earns its place; no redundancy.

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

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

For a simple removal tool with two required params and no output schema, the description is largely complete. It could mention return value but is adequate.

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

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

Schema coverage is 100% with both parameters described. The description adds no further semantics beyond the schema, 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 clearly states the action ('Remove a file from a knowledge collection') and the resource, and distinguishes itself from deletion of the file itself. Among siblings, 'collections_add_file' is the counterpart.

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 explicit guidance on when to use this tool vs alternatives (e.g., files_delete). It does not mention when not to use or provide context for choosing this tool over other file-related 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?

No annotations provided, so description bears the burden. It discloses non-destructive behavior: collection and files remain. No mention of permissions or side effects, which is acceptable for a simple unassignment.

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

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

Two sentences, front-loaded with the action. Every word adds value, no redundancy.

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

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

Simple tool with no output schema. Description covers what it does and what it does not do. Missing return value or result type, but contextually adequate.

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

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

Schema coverage is 100% with clear descriptions. The description does not add extra meaning beyond the schema; baseline 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 clearly states the action: 'Remove a knowledge collection from an AI agent.' It distinguishes from deletion by noting collection and files are not deleted. The sibling tool 'collections_assign_agent' implies the inverse. Specific verb+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?

No explicit when-to-use or when-not-to-use. The description clarifies that only the assignment is removed, which helps avoid misuse, but no alternatives or prerequisites are mentioned.

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

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

No annotations provided, so the description must carry the burden. It describes the action but does not disclose behavior on duplicate channels (e.g., overwrite vs. error) or authentication requirements, leaving gaps.

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 with clear headings and bullet points. Every sentence adds value, no wasted words.

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

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

For a simple add-channel tool, the description covers purpose, usage, and prerequisite. Missing behavior on duplicates is a minor gap, but overall sufficient given schema coverage and tool simplicity.

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

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

Schema coverage is 100%, so the schema already describes all parameters. The description adds no additional meaning beyond the prerequisite for contact_id, resulting in a baseline score of 3.

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

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

The description clearly states the action: 'Link a new channel identity ... to an existing contact.' It uses a specific verb and resource, and distinguishes itself from sibling tools like contacts_find and contacts_update.

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

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

Explicitly lists three 'When to use' scenarios and a prerequisite ('Requires contact_id from contacts.find'), providing clear context for tool selection.

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?

No annotations provided, so description carries burden. Indicates it's a search (read) operation, but does not disclose details like error handling or auth. Adequate for a simple search.

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 perfectly front-loaded and concise: purpose first, usage guidance second. No wasted words.

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

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

Given low complexity (2 params, no output schema), description covers purpose, usage, and parameter hints adequately. Lacks output format but still 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 coverage is 100%, so baseline is 3. Description adds example usage ('username or phone number') but not critical new info beyond schema descriptions.

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