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

Annotations already provide readOnlyHint=false, idempotentHint=true, etc. The description adds valuable context: that verification is fully offline, that activation-by-order involves an outbound HTTPS POST, and that activation unblocks writes. 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?

Three sentences front-load the purpose, then detail usage. Every sentence is informative without waste. The structure is clear and efficient.

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

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

Given no output schema, the description covers the tool's behavior well (modes, network call, offline verification, unlocking writes). It could mention the return value or status, but it's sufficient for most use cases.

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 description adds significant meaning beyond the schema. It explains the two modes (key vs. email+orderId), when to omit each parameter, and the server's behavior in mode 2. This greatly aids correct parameter selection.

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 activates a commercial license and describes two modes. However, it does not explicitly distinguish this tool from related siblings like license_status or request_commercial_license, which slightly reduces clarity.

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

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

The description provides precise guidance: 'Activate a commercial license. Two modes — provide exactly one:' followed by detailed explanations of each mode. This tells the agent exactly when and how to use the tool, including conditions for each mode.

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

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

Annotations already provide idempotentHint=true and destructiveHint=false. The description adds context about storage format ('[Attachments: ...] on the ticket line') and restates idempotency. It discloses the effect without contradicting annotations. Additional traits like authorization or side effects are not covered but the tool is simple.

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 a single sentence with a parenthetical clarification, no redundancy, and all information is front-loaded. Every word adds meaning.

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 (attaching to a ticket), the description adequately covers the action, idempotency, and storage format. No output schema exists, so return value is not explained, but it's implied success. Minor gap: no mention of required permissions or error conditions.

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 low (33%) with only the 'attachment' parameter described as 'A file path or URL.' The description reinforces this but does not elaborate on 'project' or 'ticket'. It adds marginal value beyond the schema for one parameter, but fails to compensate for the other two underscripted 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 the verb 'Attach' and resource 'to a ticket', specifying that it attaches a file path or URL. It distinguishes itself from siblings like remove_attachment by focusing on adding, and includes idempotency detail. The resource and action are unambiguous.

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

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

The description implies usage for adding attachments to tickets but does not provide explicit when-to-use or when-not-to-use guidance. No alternatives are mentioned, though sibling remove_attachment exists. Preconditions (e.g., ticket existence) are not discussed.

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

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

Annotations provide no safety profile; description adds that slug is derived and de-duplicated, and returns the new record. However, it doesn't disclose whether the operation is idempotent, potential side effects, or authentication needs.

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

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

Description is concise at three short sentences, front-loading the main action. No filler, but could be more structured to improve scannability.

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 no annotations, the description lacks completeness. It doesn't explain optional parameters, expected response format beyond 'returns the new company record', or error conditions. Insufficient for a tool with 4 parameters and no schema descriptions.

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

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

Schema description coverage is 0%, so description must compensate. It only explains 'project' (implicitly) and 'name' (slug derivation), but omits 'notes' and 'domain' entirely. Two of four parameters remain undocumented.

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 creates a company in the project's CRM, with slug derivation and deduplication. It distinguishes from sibling add_* tools by targeting companies, but doesn't explicitly differentiate from add_contact or add_lead.

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

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

No guidance on when to use this tool versus alternatives like add_contact or add_lead. The description only implies usage for creating companies, but does not specify prerequisites or when-not-to-use 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?

Annotations are minimal (readOnlyHint=false, etc.). Description adds that it creates a new record and returns it, but doesn't detail side effects, permissions, or duplicates. Neither contradicts annotations.

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

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

Two concise sentences with all key information front-loaded. 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 11 parameters and no output schema, description covers basic purpose and main parameters but omits 'project' and doesn't detail return structure or required fields beyond kind. Some gaps remain.

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

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

Description lists most parameters but misses 'project'. Adds some context (e.g., kind enum, template source) but schema coverage is low (18%) and descriptions for many parameters are just names. Partial compensation.

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

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

Clearly states verb 'Record' and resource 'contract or license on a CRM company'. Differentiates from siblings like 'update_company_agreement' and 'remove_company_agreement'.

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?

Describes what it does but lacks explicit guidance on when to use vs alternatives. No exclusions or prerequisites mentioned.

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

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

Annotations are all false so the description carries burden. It notes contact ids are unique within company, which is useful. However, lacks details on side effects, permissions, 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?

Two short, precise sentences with no waste. Front-loads the primary purpose and adds a key constraint (unique id).

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?

Missing important context: no return value description (no output schema), no explanation of the required 'project' parameter, no error conditions (e.g., duplicate id behavior). For a creation tool, more guidance is needed.

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 low (17%); description lists fields (name, email, role, phone) but provides no syntax or validation rules. Does not explain 'project' parameter which is required. Adds moderate value 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?

Clearly identifies the verb (add), resource (contact), and specifies fields (name, email, role, phone) and target (company). Differentiates from siblings like update_contact or remove_contact.

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. Implicitly for creating a new contact, but no exclusions or context about prerequisites or preferred use cases.

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

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

Annotations show readOnlyHint=false, confirming a write operation. The description adds that the message starts pending review, but no details on side effects or authorization beyond what is implied.

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

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

Two concise sentences with front-loaded purpose and 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?

Covers basic purpose and use case but omits lifecycle details like what happens after pending review or any prerequisites beyond the required project parameter.

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

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

The description does not explain any parameters; with 50% schema coverage, the description should compensate but does not, leaving undocumented parameters like body, from, subject without 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?

The description clearly states 'add an incoming message to the CRM inbox' and specifies that it starts pending review, distinguishing it from sibling tools like review_crm_message.

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 indicates the tool is for logging inbound emails/leads needing triage and approval, providing clear context but not explicitly excluding other tools like submit_crm_intake.

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 append-only behavior, auto-numbering (ADR-<n>), and that relevant ADRs surface in work packets. Annotations (readOnlyHint=false, destructiveHint=false) are consistent with this, and the description adds useful context beyond the annotations.

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

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

The description is two sentences with no fluff. It front-loads the core action and appends key details. 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?

The description covers the tool's purpose, behavior, and key constraints. It does not mention return values or error handling, but for an append tool with no output schema, this is adequate. Minor room for improvement.

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 83%, close to the high threshold. The description broadly maps to the parameters but does not add significant meaning beyond what the schema already provides (e.g., that 'tickets' is an array). Qualitative context is limited.

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 appends a new ADR to a project's decision log, specifies the fields (context, decision, consequences, tickets), and distinguishes from sibling tools like list_decisions. The verb 'append' and resource are explicit.

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: it is append-only and never rewrites prior ADRs. It also hints at the value of ADRs surfacing in ticket work packets. However, it does not explicitly state when not to use it or mention alternatives for editing or viewing decisions.

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

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

The description adds some behavioral context beyond annotations: it indicates the tool is a mutation (adds a feature) and returns a ticket ID. However, it does not disclose side effects, authorization needs, or what happens to existing data. Annotations are all false, so the description partially compensates but not fully.

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

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

The description is extremely concise, consisting of two short sentences that immediately convey the core action and return value. Every word is purposeful, and there is no superfluous or redundant 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?

Despite having 12 parameters and no output schema, the description is minimal. It does not explain what a 'feature' is, how the board is identified, or what mandatory parameters (like project and title) are required. The agent lacks enough context to use the tool confidently without additional schema inspection.

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 58% schema description coverage, the schema provides meanings for some parameters (e.g., ref, dueDate, newFile). The description adds no additional parameter information beyond what the schema already provides. The baseline for moderate coverage is 3, and the description does not improve upon it.

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

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

The description clearly states the action ('Add a feature') and the specific resource ('to a board's featurelist.md'). It also mentions the return value (new ticket ID), making the tool's purpose unmistakable. This distinguishes it from similar tools like add_features_bulk or commit_feature.

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

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

The description provides no guidance on when to use this tool versus alternatives such as add_features_bulk or commit_feature. There is no mention of prerequisites, context, or exclusions, leaving the agent to infer usage from the name alone.

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

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

Annotations are all false, so the description carries full burden. It mentions that the tool 'persists' ideas and 'returns created tickets', indicating it is a write operation with a return value. However, it lacks details about potential destructive behavior, authentication needs, or rate limits.

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) and front-loaded with the core purpose. Every word 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?

Given the moderate complexity (array of objects with multiple properties) and lack of output schema, the description is adequate but incomplete. It mentions the return value ('Returns the created tickets') but does not explain how failures are handled, nor does it contrast with related tools like 'commit_feature' or 'add_feature'.

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

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

Schema description coverage is 0%, so the description must compensate but fails to do so. It does not explain any of the parameters (e.g., 'project', 'features', or nested fields like 'title', 'labels', etc.). The description only mentions 'features' indirectly in the context of brainstorming, providing no additional meaning over the raw schema.

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

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

The description clearly states the tool adds several features at once, using the verb 'add' and specifying 'several features' as the resource. It distinguishes itself from the sibling tool 'add_feature' by emphasizing bulk operation.

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 context for when to use the tool ('after brainstorming: you generate the ideas, this persists them'). It implies a specific workflow but does not explicitly state when not to use it or suggest alternatives like the singular 'add_feature'.

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

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

The description explains idempotent behavior (calling with same title updates in place), avoids destructive overwrites (numeric suffix for slug collisions), and reveals an automatic side effect (keyword-matching into work packets). These details add value beyond the annotations (idempotentHint=true, destructiveHint=false), providing practical behavioral context for the agent.

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

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

The description is three sentences, each adding crucial information: the primary action, the update behavior and slug handling, and the side effect. No extraneous words, well front-loaded with the core purpose.

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

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

For a write tool with three parameters and no output schema, the description covers input expectations (title, content, project context), behavior on repeated calls, naming conventions, and automatic integration. It does not mention the return value or how to confirm success, but the idempotentHint and real-world usage patterns reduce the need for that detail.

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

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

The description clarifies how the 'title' parameter maps to a filename via slugification and explains the update logic for same-title calls. The 'content' parameter is clearly described as markdown body. The 'project' parameter is implied through 'board's kb/ folder' but not explicitly defined. Given schema description coverage of 67%, the description compensates with meaningful additional context beyond the schema's own descriptions.

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

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

The description clearly states the action (write a markdown doc into kb/ folder) and the resource (markdown doc in board's kb/). The title 'Add/update a kb doc' reinforces the dual behavior. However, it does not explicitly distinguish this tool from sibling tools like list_kb_docs, get_kb_doc, or search_kb, relying on the verb 'write' to imply it is a create/update operation.

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 is provided on when to use this tool versus alternatives. While the description implies it is for adding or updating knowledge base documents, it does not mention scenarios where one might prefer search_kb or get_kb_doc instead. The agent must infer usage from context.

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

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

The description reveals behavioral traits beyond annotations: a default status 'new' with a pipeline flow, and optional fields ('value', 'lat/lng') that affect the pipeline and leads map. Annotations only indicate non-read-only and non-destructive, so this adds meaningful context.

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

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

Two concise sentences front-load the core purpose and key defaults, with no extraneous information. Every sentence provides value without redundancy.

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

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

Given the complexity (10 parameters, no output schema), the description covers the essential creation logic and default behavior but omits details like return value, error handling, or duplicate prevention. It is adequate for a simple CRUD tool but incomplete for full contextual understanding.

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

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

With only 10% schema description coverage, the description compensates partially by explaining 'name' (implied required), 'value', and 'lat/lng' usage. However, it fails to describe 7 out of 10 parameters (city, email, source, company, status, etc.), leaving significant gaps for an AI agent to understand proper invocation.

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 ('Add a sales lead'), the target store ('project's leads store (crm/leads.json)'), and distinguishes from siblings like 'list_leads' or 'enrich_lead' by focusing on creation. The mention of default status and pipeline context adds specificity.

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 this tool is for initial lead creation by mentioning default status 'new' and pipeline stages, but it lacks explicit guidance on when to use it versus alternatives like 'enrich_lead' or 'convert_lead'. No exclusion criteria or alternative references are provided.

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

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

Annotations already indicate non-readonly, non-destructive behavior. The description adds context that the defined area is used by leads_map to tag leads and roll up counts/value, which is beyond the annotations. No contradictions.

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

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

Two sentences, each adding value: first defines the tool's action, second explains the integration with leads_map. 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 definition tool with 5 required parameters and no output schema, the description covers the main functionality and downstream use. However, it lacks explanation of the 'project' parameter and does not specify coordinate format or constraints.

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

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

The description explains the purpose of most parameters (name, lat, lng, radiusKm) but does not mention the 'project' parameter. Schema coverage is only 20%, so the description partially compensates but misses important context for a required 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 clearly states the verb 'Define' and the resource 'circular geographic area' with specific attributes (name, centre lat/lng, radius km). It also explains the downstream effect on leads_map, distinguishing it from sibling tools like update_lead_location.

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

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

The description implies usage when defining lead areas for the leads map, but does not explicitly state when to use this tool versus alternatives, nor does it provide exclusion criteria or prerequisites.

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

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

Annotations indicate readOnlyHint=false (mutating) and destructiveHint=false, which aligns with 'append'. The description adds detail about timestamping and building history, but does not disclose potential side effects 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?

The description is two sentences, front-loaded with the core action, and includes essential details (kind options, timestamp) without 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 covers the basic operation but lacks details on return behavior, optional parameter defaults (e.g., 'at' defaults to now), and parameter format expectations (e.g., id like 'L3'). Given the absence of output schema, more context would be helpful.

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 40% (only 2 of 5 parameters have descriptions). The description explains 'kind' with enum values and mentions 'note', but does not clarify 'project', 'id', or 'at'. It partially compensates for low schema coverage.

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

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

The description clearly states the action (append a touchpoint) and the resource (lead's interaction log). It distinguishes from siblings like add_lead, enrich_lead, and convert_lead by focusing on interactions.

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 logging interactions but does not explicitly state when to use this tool versus alternatives like add_crm_message or add_contact. No exclusions 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?

Annotations indicate readOnly=false and destructive=false, so the description correctly implies a non-destructive write. It adds that the tool returns the new comment and total count, and mentions threading behavior, covering key traits beyond annotations.

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

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

Two sentences, front-loaded with purpose and key differentiator. No wasted words, essential information prioritized.

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 explains the return value. It covers the main purpose and threading behavior. Lacks error conditions or edge cases, but sufficient for a simple create 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 high (80%), so baseline is 3. The description adds context for parentId (where to obtain it) but does not elaborate on other parameters beyond schema descriptions.

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

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

The description clearly identifies the action ('Add') and the resource ('threaded comment to a gallery asset'), and distinguishes it from pin annotations, making it unambiguous.

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

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

The description explains how to use parentId for replying to existing comments, implying when to include it. It distinguishes from pin annotations but could be more explicit about when not to use this tool vs alternatives like list_media_comments or remove_media_comment.

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

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

Annotations are all false, so the description carries the burden. It discloses the side effect 'Re-renders all pages so theme/gate stay consistent,' which is a key behavioral trait. However, it doesn't clarify if the operation is destructive or idempotent, but the 'update' implication and lack of destructive hint suggest non-destructive.

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, using two sentences to convey purpose, output, and a notable side effect. It is front-loaded and free of unnecessary detail.

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 5 parameters and no output schema, the description lacks details about return values, error conditions, prerequisites (e.g., project existence), and conflict handling. The side effect is mentioned, but overall completeness is moderate.

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 schema description coverage at 40%, the description adds minimal value: it mentions 'title and sections' but does not clarify 'project' or 'seo' beyond what's in the schema. The baseline is 3 due to coverage, and the description does not significantly enhance understanding of parameters 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 adds or updates a sub-page of the project site, specifying the output path (site/<slug>.html) and distinguishing from set_site for the home page. It is specific and unique among sibling tools.

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

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

The description explicitly says not to use for home page (managed by set_site), implying use cases for sub-pages. It could be improved by mentioning alternative tools like set_page_seo for SEO-only updates, but the current guidance is clear enough.

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

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

Annotations already indicate non-readOnly, non-destructive, idempotent. Description adds no further behavioral details such as error handling, duplicate behavior, or 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?

Description is concise (one sentence) and front-loaded, but could include parameter details without significant bloat.

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

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

For a simple tool with two string params and no output schema, the description provides adequate purpose context but lacks parameter semantics and behavioral details, making it minimally 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 0%. Description fails to explain what 'name' and 'project' represent, leaving the agent without semantic guidance for parameter values.

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 states specific verb 'Add' and resource 'product to a board's product list', and provides usage context for tagging tickets. It clearly distinguishes from siblings like remove_product.

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

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

Description implies when to use (for tagging tickets) but does not explicitly contrast with alternatives or state when not to use. No exclusion guidance provided.

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

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

The description discloses key behavioral traits: comments appear in get_work_packet.reviewComments, can send ticket back to next_task, and are recorded on audit history. Annotations are all false, so no contradiction; the description adds significant context beyond the annotations.

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

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

Three sentences provide all necessary information without redundancy. The first sentence states purpose, the second explains behavioral consequences, and the third mentions audit logging. 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 covers input semantics, behavioral effects, and ties to other tools (get_work_packet, next_task). It is complete for an agent to understand when and why to use 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?

Schema coverage is 67%, with some parameters described. The description adds context that the comment can be anchored to a file and line, and that it's PR-style review feedback. This adds moderate value 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 verb 'attach', the resource 'ticket', and the optional anchoring to file and line. It distinguishes from sibling tools like 'list_review_comments' and 'resolve_review_comment' by specifying the action.

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

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

The description explains that unresolved comments surface in the next work packet and, when ticket is in Review, send it back to queue. This provides clear context on when to use the tool. It does not explicitly state when not to use, but the usage is well implied.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description explains the idempotent behavior: 'Calling again with the SAME title updates in place.' It also discloses extraction behavior from path/url, auto-detection of title/source, and the needText response for problematic inputs. No contradictions with annotations.

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

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

The description is concise at 6 sentences, well-structured with a clear opening, then methods in priority order, edge case handling, and sibling differentiation. No fluff—every sentence provides essential information.

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

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

With 8 parameters, no output schema, and moderate complexity, the description covers input methods, auto-detection, update behavior, RAG indexing, and error returns (needsText). It fully prepares the agent for correct invocation without needing additional 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?

Despite high schema coverage (88%), the description adds significant meaning: priority order of parameters, auto-detection logic for title and source from url/path, slugification of title, and update behavior. It explains that passing title/source overrides auto-detection and that tags are topical. These details go beyond the schema descriptions.

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

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

The description clearly states the verb 'Save' and resource 'research source', specifies it goes into a board's sources/library, and explicitly distinguishes from sibling tools 'add_kb_doc' and 'append_research' by saying 'Use this for the sources; use add_kb_doc / append_research for YOUR notes about them.'

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

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

The description provides explicit guidance on the three input methods in priority order (path, url, text), explains when to use which, and tells how to handle scanned PDFs or JS-rendered pages. It also clearly states when to use alternative tools for notes about sources.

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

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

Annotations (readOnlyHint=false, idempotentHint=false) indicate mutation, but the description adds return info: 'Returns the new annotation (with a stable id) and the total count.' No contradiction with annotations.

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

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

Two sentences that efficiently convey purpose and return behavior. No unnecessary words, clear and front-loaded.

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

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

Given 6 parameters, 50% schema coverage, no output schema, and few annotations, the description explains the return value but fails to describe key parameters like 'project', 'name', and 'author'. The term 'pin-based' could be elaborated. Adequate but incomplete.

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 50% (3 of 6 parameters described). The description restates x/y coordinates but adds no new meaning. Required parameters 'project' and 'name' are not described, and 'author' is also missing. The description does not compensate for the low schema coverage.

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

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

The description clearly states the action ('Add a pin-based comment/annotation') and the resource ('to an asset'). It distinguishes from sibling tools like add_media_comment by specifying 'pin-based' and optional coordinates.

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 pinning annotations on assets but does not explicitly state when to use this tool versus alternatives like add_media_comment or remove_annotation. No when-not or conditions are provided.

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

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

Discloses important behaviors (creates doc on first call, appends later, findings accrue in kb) beyond the minimal annotations, though could mention potential side effects or error conditions.

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, no fluff. 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?

Sufficient for a simple append tool given no output schema; covers creation vs appending and durability, but could elaborate on ticket existence assumptions or rate limits.

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 little beyond the input schema; the 'finding' description is already present in the schema, and 'project' remains undefined. Schema coverage is moderate (67%), so description should compensate more.

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 'Capture ONE research finding into a ticket's durable research doc' with a specific verb and resource, and explicitly distinguishes from sibling tool append_scratchpad.

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 'Prefer this over append_scratchpad' and advises calling it repeatedly during research, giving clear when-to-use/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?

The description adds behavioral context beyond annotations by specifying that existing notes are preserved and that ticket ID mentions surface in work packets. However, it does not disclose potential side effects like file size limits, error conditions, or whether the file is created if missing. With annotations already marking it as non-destructive and a write operation, the description adds moderate value.

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 sentences, front-loading the core action and effect. Every sentence adds value: the first defines the operation, the second adds a useful linking feature. 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 append tool with no output schema, the description covers the primary action and the ticket-linking feature. However, it lacks details about error handling (e.g., invalid project, missing scratchpad), formatting behavior, and whether the append is atomic. It is minimally adequate but has noticeable 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 describes 'text' as 'Text to append' and does not describe 'project'. The description does not provide additional meaning for either parameter: it does not clarify what 'project' represents (e.g., ID or name) or imply any constraints beyond the schema. The ticket ID mention is a usage tip, not parameter semantics.

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 ('append'), the resource ('board's scratchpad.md'), and the effect ('preserving existing notes'). It also introduces the unique feature of linking to ticket IDs, distinguishing it from siblings like set_scratchpad (overwrite) and get_scratchpad (read).

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 (to add notes without overwriting) and provides a specific usage hint about ticket IDs. However, it does not explicitly state when not to use it or mention alternatives (e.g., set_scratchpad for overwriting), leaving some room for ambiguity.

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

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

Discloses that the tool replaces site config and renders, adding detail beyond annotations (destructiveHint: true). No contradictions.

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

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

Two sentences: first covers action and effects, second gives after-use guidance. No redundant information.

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

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

Given no output schema and moderate complexity, description covers purpose, usage, behavioral effects, and refinement steps. Adequate for an AI agent to understand and 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?

Schema coverage is low (33%), but description adds context by listing what the tool sets (title, tagline, theme, sections, starter pages). However, it does not explain individual parameters like 'project' or the enum values beyond listing template types.

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 verb 'Seed' or 'Start' the website from a starter template (landing, docs, blog). Distinguishes from siblings like set_site/add_page by noting them as refinement tools.

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

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

Explicitly says 'Replaces the current site config — use set_site/add_page to refine after', providing clear when-to-use and when-not-to-use guidance with alternative tools.

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

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

Annotations indicate idempotent, non-destructive writes. The description adds behavioral context: it replaces any existing sprint label and allows clearing with null. This goes beyond annotations but does not disclose potential errors, rate limits, or exact response format.

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 a single, well-structured sentence that front-loads the action and includes the key special case. Every word adds value; 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?

For a simple tool with 3 params and no output schema, the description covers core functionality and the null case. However, it lacks details on response, error handling, and atomicity for multiple tickets. It is minimally adequate.

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

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

Schema description coverage is only 33% (sprint has a description matching null usage). The tool description does not clarify what 'project' refers to (ID? name?) or the format of 'tickets' (array of ticket IDs). The implied meaning from context is insufficient given the gap.

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

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

The description clearly states the action ('Move one or more tickets into a sprint'), specifies the mechanism (sets sprint:<name> label, replacing existing), and includes the special case of null to send tickets back to backlog. This distinguishes it from related sibling tools like create_sprint or update_task.

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 for when to use (assigning tickets to a sprint) and the null case for backlog. However, it does not explicitly state when not to use this tool or mention alternative tools (e.g., set_status for single ticket updates).

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

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

Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds context that the tool derives settings from existing tracking and errors if none exist, which are important behavioral traits. No contradiction with annotations.

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

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

The description is a single sentence that is clear and front-loaded, containing the core purpose and key constraints. However, it lacks parameter explanation, though this is partly compensated by the brevity.

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 one parameter, no output schema, and good annotations, the description covers the main purpose and error condition. However, missing parameter documentation and lack of explicit usage context (e.g., when to use vs. set_analytics_config) leave 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 input schema has a single required parameter 'project' with no description (0% schema coverage). The description does not explain what 'project' is or its format, leaving the agent to guess. Since the description fails to add any meaning beyond the schema, this dimension scores low.

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 'Derive the external analytics read config from the site's existing tracking settings' and mentions enabling the proxy. It distinguishes the tool from siblings like 'set_analytics_config' by automating configuration based on existing settings.

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 the tool: to avoid retyping the domain/property. It also states an error condition when no analytics are configured, implying it should not be used in that case. However, it does not explicitly name alternative tools such as 'set_analytics_config' for manual configuration.

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

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

Adds value beyond annotations by describing validation (company exists, contact belongs) and storage behavior (crm/bookings.json, status 'scheduled'). Annotations are non-contradicting.

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, front-loaded with purpose, then validation, then storage details. 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?

Good coverage given complexity: explains workflow, validation, and storage. Missing return value info, but acceptable since output schema not provided. Sufficient for a booking tool.

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

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

Explains 'company' and 'contact' validation relationship and 'at' as ISO timestamp. Schema coverage is 50% but description partially compensates. Other parameters (type, notes, subject, durationMins, project) are not clarified.

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

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

Description clearly states it schedules calls/demos/meetings with a CRM company and optional contact. It distinguishes from siblings like list_bookings and cancel_booking, but does not explicitly differentiate.

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 when to use (scheduling) and mentions validation steps, but lacks explicit when-not-to-use or alternative tools. Context is implied but not explicit.

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

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

Annotations already declare readOnlyHint=true, so the tool is safe. The description adds behavioral context by explaining the ranking method (keyword overlap and shared product), which helps the agent understand what the tool does beyond the schema. No contradictions with annotations.

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

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

The description is very concise with only two sentences. The first sentence defines the action, and the second provides usage guidance. Every word contributes value without redundancy.

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

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

The description covers the core purpose and usage but lacks details about the output format (e.g., how ranks are presented, what fields are returned). Given the tool has no output schema, the description could be more informative about the expected return value, which is a gap.

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

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

The description adds meaning beyond the schema by explaining the two modes: using a bug ticket or providing an ad-hoc title/description. It also mentions 'shared product' which relates to the required 'project' parameter. Schema coverage is only 25%, so the description compensates well.

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: given a bug, rank existing features by impact using keyword overlap and shared product. It uses a specific verb ('rank') and resource ('features'), and it distinguishes itself from sibling tools like 'log_bug' or 'get_regressions' by focusing on impact scanning.

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 it when logging a bug to spot regressions and linkage candidates,' providing a clear usage context. However, it does not mention when not to use this tool or list alternatives, which would strengthen 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?

The disclosure of idempotency adds value beyond annotations. The description is consistent with annotations (idempotentHint=true, destructiveHint=false). It could mention other behaviors like notifications or refunds, but the existing context 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 extremely concise, using two sentences to convey core purpose and idempotency. No extraneous words exist; every sentence adds essential 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?

While the description covers purpose and idempotency, it fails to explain the 'project' parameter. Given three parameters and no output schema, the description should be more thorough to fully guide the agent.

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

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

Schema description coverage is low (33%). The description only clarifies 'id' and 'reason' but omits any explanation of the 'project' parameter, which is required. This leaves a significant gap in understanding the tool's input requirements.

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 (cancel), the resource (booking), and specifies the id comes from list_bookings. It effectively distinguishes from sibling tools by being specific to booking cancellation.

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 indicates when to use the tool (with a booking id from list_bookings) and mentions idempotency. However, it does not explicitly state when not to use it or provide alternatives, leaving some room for ambiguity.

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 it uses heuristics similar to validate_feedback, labels the request as ask:<source>, and records the requester. Annotations are minimal (no readOnly, etc.), so the description adds some behavioral context but does not fully explain side effects or creation process.

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 at two sentences, front-loading the action and important characteristics. However, the second sentence could be integrated more smoothly, and the structure is adequate but not exemplary.

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

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

There is no output schema, and the description does not explain what the tool returns after structuring a request (e.g., ticket ID, confirmation). Given the complexity of creating a ticket, this is a significant gap in completeness.

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

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

Schema coverage is 75%, and the description adds meaningful context: 'source' becomes part of the label, and 'from' is recorded in the description header. This goes beyond the schema descriptions for those parameters, though 'project' remains unexplained.

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 structures pasted external requests into features or bugs using heuristics, specifying input types (Slack message, email) and output labeling (ask:<source>). It distinguishes itself from a live intake listener.

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 says 'paste-to-structure, not a live intake listener,' which gives some usage context. However, it does not explicitly state when to use this tool over alternatives like validate_feedback or other intake tools, nor does it provide exclusion criteria.

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

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

Beyond annotations (idempotentHint=true, destructiveHint=false), the description adds that 'Hand-added sections are preserved' and clarifies default behavior ('done defaults to true'). This provides useful behavioral context not captured in structured fields.

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

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

The description is concise, with three short sentences that front-load the action. Every sentence adds value: the first states the primary action, the second mentions preservation behavior, and the third clarifies a default.

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 toggle tool with no output schema, the description covers the main action, default, and an important preservation detail. It could mention error cases or return value, but overall it is fairly complete given the tool's simplicity and the existing schema descriptions.

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 50% schema description coverage, the description adds meaning for 'index' (1-based) and 'done' (defaults to true). However, it does not explain the 'ticket' and 'project' parameters, which are required. The description partially compensates but does not fully cover the gap.

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

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

The description states the specific action ('Toggle the checkbox') and the resource ('acceptance criterion on a ticket's requirements pad'). It clearly distinguishes from sibling tools like 'set_requirements' and 'get_requirements' by focusing on a single toggle operation.

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 by describing the toggle action and noting that 'done defaults to true', but it does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. The context is clear enough for a simple operation.

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

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

Annotations already indicate readOnlyHint=true and openWorldHint=true. The description adds substantial detail: exactly one GET request to a specific URL, no request body (privacy), compares version locally, provides download links, and fails soft on network issues. No contradictions.

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

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

The description is a single, well-structured paragraph that front-loads the primary purpose. Every sentence adds value: technical details, privacy assurances, behavior, and error handling. It is appropriately sized without verbosity.

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

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

Given no parameters and no output schema, the description covers the tool's behavior comprehensively: action, URL, comparison, returned information, and error handling. It lacks only explicit output structure, but that is acceptable without an 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?

The input schema has zero parameters, with 100% schema coverage. The description correctly implies no parameters are needed. Baseline for no parameters is 4, and the description aligns perfectly.

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 explicitly checks for a newer FeatureBoard release via an HTTPS GET request to a specific URL. It naturally distinguishes itself from all sibling tools, none of which perform update checks.

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 the tool (to explicitly check for updates) and clarifies that it never runs automatically (no polling or background checks). It also mentions soft failure handling. Though no explicit 'when not to use' is given, 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?

Discloses that it uses cached git log/numstat, pagination with worst-drift first, and that totals cover all tickets. Annotations (readOnlyHint=true) are consistent. 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?

Packed with information but not overly verbose. Each sentence adds unique value. Could be slightly better structured with bullet points, but efficient overall.

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

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

Despite no output schema, the description explains the return format (per-ticket drift, overall churnAccuracy) and pagination semantics. Complete for a reconciliation 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?

Adds value beyond schema: explains limit/offset mirror list_tasks, driftThreshold filters but totals still cover all, full ignores pagination. Schema covers 80% of parameters; description compensates for the missing project 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?

The description clearly states it compares work log and git-actual numstat for Done tickets with tagged commits, reporting per-ticket and overall churn accuracy. This is specific and distinguishes from any sibling tool.

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

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

Provides context on when to use (Done tickets with tagged commits), pagination behavior (limit/offset, full flag), and drift threshold filtering. However, it does not explicitly exclude alternative tools or 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?

The description discloses multiple behavioral traits beyond annotations: refusal conditions, no-op behavior, safety check for unrecognized paths, and branch preservation. This aligns with and expands on the 'destructiveHint' and 'idempotentHint' 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 three concise sentences, each adding distinct value. The main action is front-loaded, and every sentence serves a purpose 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 cleanup tool with destructive consequences, the description covers all critical aspects: primary action, refusal conditions, edge cases (no worktree, unrecognized path), and post-conditions (branch intact). No further context is needed given annotations and sibling tools.

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

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

The description adds meaning to the 'force' parameter by linking it to uncommitted changes and safety. For 'project' and 'ticket', it provides context via example usage ('ticket/<ticket> branch'). With only 33% schema coverage, the description compensates adequately.

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

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

The description uses a specific verb ('remove') and resource ('ticket's git worktree'), clearly distinguishing it from its sibling 'create_worktree'. It explicitly states the action and context.

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 on when to use (after branch merge), when it refuses (uncommitted changes without force), and when it no-ops (no worktree registered). It lacks explicit alternatives but effectively sets usage boundaries.

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

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

Annotations indicate idempotent and non-destructive. Description adds beyond: explains refusal behavior, file writing, Slack posting (error tolerance), and rollover modes. No contradiction with annotations.

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

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

Single paragraph covers all behaviors without redundancy. Front-loaded with core action. Could benefit from slight structuring (e.g., bullets for modes) but remains 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?

Comprehensive for a complex tool: covers parameters, conditions, outputs, error handling, and rollover modes. Lacks explicit return shape details but notes 'result shape unchanged with rollover section', which is adequate given no 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?

Schema coverage is 80% (project lacks description). Description greatly enriches parameter understanding: force effect, rolloverMode behavior, nextSprint usage, and output paths. Significantly adds meaning 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 'Close a sprint and generate four audience-specific close-out reports' with a specific verb and resource. It distinguishes from siblings like create_sprint and list_sprints by detailing the unique outcomes (reports, rollover handling).

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

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

The description implies when to use (finalize a sprint, generate reports) and provides conditions (refuses with open tickets unless force). It doesn't explicitly list alternatives but context from siblings makes 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?

Annotations already declare readOnlyHint=true (safe read). The description adds behavioral details: recursive mapping, regex-based symbol extraction (with capping), and that results are ordered 'worst first' for split candidates. It doesn't mention performance implications or recursion depth limits, but it sufficiently goes beyond the annotations.

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

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

The description is two sentences, each packed with valuable information. The first sentence covers the core mapping functionality and outputs, the second details the optional symbols feature. No unnecessary words; every phrase 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?

For a tool with 4 parameters and no output schema, the description gives a good high-level overview but lacks specifics like the cap value for symbols, performance implications, or the exact structure of the returned data. While 'worst first' clarifies ordering, more detail on output format would improve completeness.

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

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

Schema coverage is low (25%) with only 'symbols' having a description. The description compensates by explaining the role of splitBytes and splitLines ('split thresholds (lines/bytes)') and that symbols:true triggers per-file symbol lists. However, the 'project' parameter is only implicitly defined as 'the project's codeLocation', lacking precise meaning. This provides some added value but not full 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 that the tool recursively maps the codebase, reports total file count and bytes, counts by extension, and identifies files exceeding split thresholds as candidates. It also explains the optional symbol extraction. This distinguishes it from siblings like list_code_files (which likely lists files) or suggest_file_split (which suggests specific splits).

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 the usefulness: 'for spotting oversized modules to decompose' and 'a lightweight symbol map for navigation.' While it doesn't explicitly name alternatives or state when not to use, the context of siblings like list_code_files and read_code_file is implied. It provides clear usage guidance without being exhaustive.

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

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

Discloses behavioral traits beyond annotations: commits changes, pushes conditionally, no-ops when disabled, mirrors pads for graduated projects, uses local git credentials, and auto-status on commit. No contradictions with annotations.

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

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

Somewhat lengthy but each sentence adds value. Front-loaded with primary action. Could be slightly more concise but remains clear 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 6 parameters, no output schema, and no annotations on complexity, the description covers all relevant context: conditions, behavioral nuances, parameter interactions, and edge cases like graduated projects.

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 50% (3 of 6 params have descriptions). The description adds meaningful context for push, paths, and message params, and indirectly covers title/ticket format. Could be more explicit about required project and ticket format but overall helpful.

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 commits and optionally pushes changes with a specific message format. It distinguishes itself from siblings like open_pull_request by focusing on the commit action.

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

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

Provides explicit guidance on when to use (git enabled), when it's a no-op (disabled), how push behavior is resolved (gitMode or explicit), and when to use paths to avoid sweeping other changes. Also covers graduated projects mirroring.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds value by specifying the ticket split into features/bugs, priority ranking, and reporting of missing linked IDs, which are not disclosed by annotations.

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

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

Two sentences with no wasted words. The first sentence front-loads the core purpose, and the second adds important behavioral detail. 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?

With only 2 parameters and no output schema, the description adequately explains the output structure (sorted list with missing IDs). Minor gap: no mention of pagination or limits, but overall sufficient for a low-complexity 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 50% (company described, project not). The description does not explain the 'project' parameter or add meaning beyond the schema. Given low coverage, the description fails to compensate.

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 a company's linked board tickets, split into features and bugs, ranked by priority, and reports missing linked IDs. This verb+resource combination is specific and distinguishes it from siblings like list_companies or list_tasks.

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 retrieving priority-ranked tickets but lacks explicit when-to-use or when-not-to-use guidance. No mention of alternatives or exclusions, making it adequate but not proactive.

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 key side effects: carries fields, marks lead won, records company, errors if duplicate. Annotations show destructiveHint=false, so no destruction warning needed. Adds value beyond annotations by detailing what gets transformed.

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 without redundancy. Each sentence adds distinct information: action, field mapping/options, and behavioral notes. Front-loaded with the core purpose.

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

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

Covers inputs, transformation, side effects, and error condition. No output schema exists, but the description adequately explains the result (company created, lead updated). Could mention response structure, 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?

Description explains the meaning of fields (name, website→domain, notes summary) and the createContact parameter's role. It complements the schema by contextualizing how parameters map to lead fields, exceeding schema descriptions.

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

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

Description clearly states the specific verb 'convert' and resource 'lead to a company', detailing field carryover and optional contact creation. It distinguishes from sibling tools like 'add_lead' or 'set_lead_status' by focusing on conversion.

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

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

Description implies use for qualified leads and warns of errors if already converted, but does not explicitly state when not to use or provide alternatives. However, the context of sibling tools (e.g., enrich_lead) provides indirect guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety and scope are covered. The description adds that it includes an overall rollup and untested tickets per product, giving output context but no behavioral traits like rate limits or error handling. With annotations, this is adequate but not exceptional.

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 core purpose, and wastes no words. Every sentence adds value: the first explains the aggregation, the second lists output components.

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 one parameter and no output schema, the description adequately covers the purpose and output shape (overall rollup, untested tickets). It does not mention any filters like date range or status, but given the tool's likely use case and annotations, this is not a critical gap.

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

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

There is only one parameter 'project' (string) with no description in the input schema (0% coverage). The description mentions 'per product' but does not clarify that 'project' likely refers to a product identifier, nor does it specify valid values or format. The agent must infer meaning, which increases ambiguity.

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

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

The description clearly states that the tool rolls up per product the count of tickets with and without recorded test runs, making testing gaps visible. It specifies the resource (tickets per product) and the action (roll up), distinguishing it from sibling tools like get_test_runs or test_runs_by_suite which focus on individual test runs or suites.

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 that the tool is for making testing gaps visible on the board, providing clear context for its use. However, it does not explicitly state when not to use it or mention alternative tools for more detailed test run analysis, missing a chance to guide agents away from misuse.

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 recipients are validated and deduplicated, and that voiceLint conditionally scores body copy as a warn-only attachment. Annotations (readOnlyHint=false) are consistent. No destructive behavior is mentioned, but the tool creates a resource, so behavioral transparency 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 three sentences covering main action, recipient processing, and a conditional feature. It is front-loaded with the core purpose. No unnecessary words, but could be slightly more 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?

No output schema exists, but the description mentions returns: campaign + stats. However, it lacks details on stats content, error conditions, or constraints like duplicate names. Given the tool's complexity (6 params, 3 required), it is minimally complete but not exhaustive.

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

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

Schema coverage is 33% with descriptions only for batchSize and recipients. The description adds context about recipient validation and batch size computation, but does not explain required parameters like project and name. For a 6-param tool, the description adds marginal value 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 creates a marketing campaign with recipient list and batch size. It specifies recipients are validated and deduplicated, and that sending is handled separately. It also mentions a conditional voiceLint feature. This distinguishes it from sibling tools like list_campaigns and get_campaign.

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 the tool is for campaign setup, leaving sending to user/connector. However, it does not explicitly state when to use this tool versus alternatives or provide exclusions. There is no direct comparison with other campaign-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?

Annotations (readOnlyHint false, etc.) are present and not contradicted. The description adds that it creates files and returns a ticket prefix, but lacks detail on side effects or permissions. Adequate but not rich.

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

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

Two sentences, directly front-loaded with the primary purpose. 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?

For a simple creation tool with 2 parameters and no output schema, the description explains what is created and hints at the return value. Missing details about ticket prefix derivation, but overall adequate.

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

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

Schema coverage is 100%, and the description adds context: 'name' is also the folder name, and 'description' is stored atop featurelist.md. This goes beyond the schema definitions.

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 creates a new board folder with specific files (featurelist.md and buglist.md) and returns a ticket prefix. It distinguishes from siblings like add_feature or create_campaign by focusing on project-level creation.

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

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

No guidance on when to use this tool versus alternatives. The description does not mention prerequisites, exclusions, or compare to similar tools like add_features or set_project_config.

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

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

Annotations show idempotentHint=true, consistent with 'create or update' semantics. The description adds useful behavioral context: the registry is stored in project config and the label-based ticket assignment mechanism. 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?

Three sentences, front-loaded with the core purpose. Every sentence adds value: first sentence defines the action, second explains labeling, third ensures compatibility. No wasted words.

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

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

For a tool with 6 parameters and no output schema, the description covers creation/update behavior, persistence, and interaction with the ticket system. It is sufficient for an agent to understand when and how to invoke 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?

Schema description coverage is 83% (5 of 6 parameters described). The description mentions 'optional start/end dates and a one-line goal' but adds minimal value beyond the schema, which already documents constraints like name format and goal being one-line.

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

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

The description clearly states the action ('Create (or update) a named sprint on a board') and the specific resource (sprint with optional dates/goal). It distinguishes from sibling tools like assign_sprint by mentioning the label mechanism and that tickets join via sprint:<name> label.

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 that the sprint registry is persisted in project config and references assign_sprint for ticket assignment. It also notes compatibility with label-only sprints from the board UI, providing context for when to use this tool versus others.

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

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

Annotations indicate idempotence and non-destructiveness. Description adds crucial details: refusal to create inside repo, reuse behavior, error conditions, and return items. No contradiction with annotations.

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

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

A single paragraph that efficiently communicates purpose, caveat, behavior, and error conditions. Slightly long but every sentence is informative. Could be split for readability.

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 specifies return items (path, branch, guidance). Covers error conditions and corner cases (non-git path, old git, directory squatting). Complete for a complex 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 covers 33% of parameters with descriptions (only baseRef). Description compensates by explaining defaults (baseRef from HEAD), branch naming convention, and worktree path pattern. Adds meaningful 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?

The description states 'Create (or reuse) an isolated git worktree for a ticket' with a clear verb and resource. It distinguishes from sibling tools like cleanup_worktree and list_worktrees by emphasizing parallel work on multiple tickets.

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

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

Explicitly says when to use (parallel ticket work) and includes a caveat about avoiding synced repos. Could improve by naming alternative tools like cleanup_worktree for removal, but the context is sufficiently clear.

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

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

Annotations provide no safety flags, so description adds value by stating it returns HTML and optionally writes to media gallery. No contradictions.

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

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

Single, well-structured sentence that front-loads purpose and adds essential details without redundancy.

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

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

Covers key aspects: purpose, output (HTML), optional save, and linking hint. Lacks explanation of side effects beyond save, but adequate for a clear 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?

Description adds context for 'company' by mentioning contacts and tickets, and 'save' behavior is explained. However, 'project' parameter is not described, and schema already covers 67% of 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?

Clearly states the tool builds a per-customer portal page with contacts and linked tickets, using specific verbs and resources. Distinguishes itself from sibling tools like list_companies or add_page.

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?

Implies usage context for building portals and mentions linking tickets with link_customer_ticket as a prerequisite. No explicit when-not 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?

Annotations indicate idempotentHint true and destructiveHint false, and the description adds that apply:true writes labels (a mutation), explains the budget interpretation, and describes the return value (dispatch groups). No contradictions are present. The description adds useful behavioral context beyond the annotations.

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

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

The description is a single dense paragraph, but every sentence adds value: purpose, budget, model assignments, effort levels, apply behavior, return type, and pairing advice. It is not overly verbose and is well-structured, though a slight separation of concerns could improve readability.

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

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

Given no output schema, the description fully explains the return value (dispatch groups with parallel sub-agents) and references internal code for further details. It covers behavior, parameters, output, and usage context (pair with daily_plan prompt). The tool is complex, and the description provides sufficient completeness for an agent to use it correctly.

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

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

Schema coverage is 75% (3 of 4 params have descriptions), and the description adds meaning: it explains the budget in terms of days/weeks, the apply parameter's effect, and the model roster with values (fable, opus, etc.) that are not captured in the schema. The description compensates well for the undocumented project 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 clearly states the verb ('Plan TODAY') and resource ('priority queue'), and specifies the scope (daily slice, default budget). It distinguishes from siblings by its unique function of assigning models and effort levels, which is not covered by other planning tools like 'plan_work' or 'plan_budget'.

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 context for when to use (daily planning, with a budget model) and mentions pairing with a prompt, but does not explicitly state when not to use or list alternative tools. There is no guidance on exclusions or prerequisites.

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 fully discloses behavior: it creates subtasks linked to the parent, deletes the parent (unless keepParent is true), and returns new tickets. This aligns with annotations (destructiveHint: true) and provides additional context beyond annotations.

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

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

The description is extremely concise with three short sentences. The main purpose is stated first ('Replace one feature with a set of linked subtasks'), and every sentence adds value without redundancy.

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

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

Given the tool's complexity (4 parameters, nested subtasks, no output schema), the description covers the core action and return value. It lacks details on error cases or prerequisites, but is sufficient for a straightforward mutation 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?

While schema description coverage is 50%, the description adds meaningful context: it explains that the subtasks parameter is user-provided and that the tool creates them. It also implies the role of the 'ticket' parameter as the parent. This compensates for missing schema descriptions.

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

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

The description clearly states the tool's purpose: replacing a feature with linked subtasks. It uses specific verbs ('Replace', 'deletes') and resources ('feature', 'subtasks'). It distinguishes from siblings like add_feature or delete_task by focusing on decomposition.

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 (to break a feature into subtasks), but does not explicitly state when not to use it or mention alternatives. Context is clear, but lacks exclusions or guidance for edge cases.

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

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

Annotations already declare destructiveHint=true, and the description adds 'permanently remove,' which is consistent. However, it does not disclose potential side effects, such as whether the task is deleted entirely or just unlinked from the board, or if the operation is reversible.

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 a single, concise sentence with no filler. However, it is too terse and could benefit from added context without being overly 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 two required parameters with no schema descriptions and no output schema, the description is insufficient. It omits crucial details about parameter usage and the delete operation's outcome, leaving the agent with significant 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 schema has 0% description coverage for parameters (ticket and project), and the description does not explain what these parameters represent. The agent lacks clarity on how to identify the task (e.g., is ticket an ID?) or the project 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?

The description clearly states the action (permanently remove), resource (task), and scope (from its board). It distinguishes the tool from siblings, as no other sibling tool targets task 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?

No guidance on when to use this tool versus alternatives or when not to use it. The description does not mention prerequisites, consequences, or related operations.

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

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

Discloses non-readOnly mutation (commit/push), details site location logic, git credential usage, and push resolution behavior. Goes well beyond annotations which only indicate open-world and non-destructive.

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?

Every sentence adds value; front-loaded with core purpose, then logically expands on location, prerequisites, and behavior. 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?

Covers prerequisites, location, push behavior, and execution context (local git credentials). No output schema, but description is sufficient for correct invocation without missing info.

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

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

Adds significant context for 'push' parameter (resolution rules) and 'project' (site location), but does not describe 'message'. Schema coverage 67% is partially compensated by description detail.

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 re-renders and publishes the site via git commit/push, distinguishing it from other tools. References to 'MCP equivalent of old website deploy' and explicit verb+resource make purpose unmistakable.

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?

Specifies prerequisite (git integration enabled) and explains push behavior resolution. Does not explicitly contrast with sibling tools, but context is clear; no alternative deploy tool exists 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?

Annotations already indicate idempotent and non-destructive behavior. The description adds 're-render the page without it', providing some context beyond annotations. No contradictions.

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

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

A single, clear sentence with no wasted words. Action is front-loaded and the meaning is immediately understood.

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 one parameter and no output schema, the description lacks explanation of what 'passcode gate' means, what 're-render' entails, and parameter semantics. It feels incomplete for an AI agent needing to invoke it correctly.

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

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

Schema description coverage is 0%, but the description does not explain the 'project' parameter at all. It only implies the target site but gives no details on format, values, or how it's used.

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 turns off the passcode gate and re-renders the page. The verb 'turn off' and resource 'passcode gate' are specific, distinguishing it from its sibling 'enable_login_gate' despite no explicit comparison.

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

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

No guidance on when to use this tool versus alternatives like enable_login_gate. No prerequisites or exclusions 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?

The description adds value beyond annotations by explaining that dismissals are append-only, future scans hide the finding and report dismissedCount, and the id is a stable hash. No contradiction with annotations (idempotentHint: true, destructiveHint: false).

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

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

The description is three sentences, well-structured with purpose, usage, and behavioral note. It is front-loaded and concise 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 mutation tool with no output schema, the description covers purpose, behavior, parameter details, and idempotency. It could mention error cases or return values, but overall it is fairly 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 67% (2 of 3 params have descriptions). The description enhances understanding by explaining the findingId is stable and shown in scans, and that reason is optional. It provides additional context 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 suppresses a scan_board_cleanup finding without deleting anything, intended for false positives or accepted risks. It uses specific verbs and resource, and distinguishes from sibling scan tools.

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

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

The description explains when to use the tool (false positives or accepted findings) and how it affects future scans. It does not explicitly mention alternatives or when not to use, 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?

Annotations indicate non-read-only (mutates), non-destructive, non-idempotent. The description adds context: validates recipients, optionally links to CRM, and voiceLint behavior (scores body and attaches 'voice' as warn-only). No contradiction with annotations.

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

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

Three sentences: first covers main purpose and key limitation, second adds optional CRM, third details voiceLint. Well-structured and front-loaded. The third sentence is slightly lengthy but still clear. Minimal waste.

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

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

No output schema; description does not mention return value (e.g., draft ID) or how to reference the draft later. It also does not explain 'project mail center' context. Given moderate complexity (6 params) and sibling tools like 'list_mail', 'get_email', some gaps remain.

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

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

Schema description coverage is 33% (only 'to' and 'company' described). The description mentions recipients are validated and CRM tie-in, but does not explain 'project', 'cc', 'subject', 'body' formats or constraints. For a tool with 6 parameters, this is insufficient additional guidance.

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 composes and saves an email draft, emphasizing it does not send. It specifies the resource ('email draft in the project mail center') and action ('compose and save'), and distinguishes from sending via explicit note. This matches 'draft_email' well.

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 says 'does not send—there is no mail connector; the user or a future connector sends', making it clear when to use (drafting) and when not (sending). It also mentions optional CRM tie-in. However, it does not name sibling tools like 'mark_email_sent' explicitly.

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 key behaviors: rejects over-limit copy, voice lint scoring (warn-only, never blocks), and that drafts are for user review. Annotations indicate write but non-destructive, and description adds important constraints beyond annotations.

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

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

Three sentences, no wasted words. Front-loaded with main action. Efficient 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?

Covers workflow (review via list_shares) and constraints (character limits, linting). No output schema, but description implies saved state with voice attachment. Slightly lacking return details but sufficient for agent usage.

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 50%, but description clarifies each parameter: text as copy with length rules, platform as enum, asset as gallery item. Adds meaning beyond schema defaults for project and platform.

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 saves a draft for a gallery item, never posts, and specifies platform-specific character limits. It distinguishes from sibling 'list_shares' by mentioning review.

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

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

Explicitly says when to use (save draft) and when not (no live-publish, never posts). Mentions alternative 'list_shares' for review. Provides clear context for usage.

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

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

Beyond annotations, the description adds that the tool upserts by ticket and derives verdicts automatically unless overridden. However, it does not disclose potential side effects, permission requirements, or error handling for write operations.

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 with key information front-loaded. No unnecessary words, but could be slightly more structured (e.g., bullet points for parameters).

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

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

Covers the recording action and optional inputs but lacks guidance on how this tool fits with sibling tools (drift_report, drift_remediate) and does not describe return behavior or error states. Adequate for a straightforward tool but could be more comprehensive.

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 meaning for the gap and files parameters beyond the schema by describing their purpose. With 57% schema coverage, the description partially compensates but does not cover the semantics of ticket, project, or verdict 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?

Clearly states the tool records a fidelity score for a single ticket in a drift run, with explicit verb and resource. Distinguishes from siblings like drift_start and drift_report by focusing on per-ticket scoring.

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?

Implies usage context (within a drift run, per ticket) and mentions upsert behavior, but does not explicitly state when to use this tool vs alternatives like drift_report or drift_remediate. No exclusion criteria.

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

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

The description adds significant behavioral context beyond the annotations. Annotations mark it as destructive (destructiveHint=true), and the description elaborates: 'file_bugs files a linked, drift-labeled bug per gap; reopen moves them back to Todo; relabel adds a drift label.' It also mentions dryRun for preview and that it records actions. No contradiction with annotations.

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

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

The description is extremely concise: three sentences that first summarize, then enumerate actions, and finally add additional options. Every sentence adds value, and the key information is front-loaded.

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

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

Given the tool's 5 parameters, destructive nature, and lack of output schema, the description covers the purpose, actions, verdicts, dryRun, and recording behavior. It does not specify the return value (though no output schema is present) or prerequisites, but it is largely complete for an actionable remediation 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?

With only 40% schema coverage, the description adds meaning to the action parameter by detailing each enum value, explains verdicts (default ['drift']), and clarifies dryRun. However, the project parameter, which is required, receives no explanation. Overall, the description compensates for most schema gaps.

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

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

The description clearly states the tool's purpose: 'One-click remediation across a run's flagged tickets' and lists the specific actions (file_bugs, reopen, relabel). This is a specific verb+resource combination that distinguishes it from sibling tools like drift_report, which only reports without applying changes.

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 the tool (when you have flagged tickets and want to apply remediation) and describes the actions and dryRun option. However, it does not explicitly state when not to use it or compare to alternatives like drift_report, which would provide clearer guidance.

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