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

Annotations are minimal (readOnlyHint=false, destructiveHint=false), so the description carries the full burden. It discloses the two-step billing process, that keywords stay PENDING until payment settles, the immediate prorated charge, and the failure behavior. It also warns against looping, which is critical behavioral context.

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

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

The description is long but every sentence earns its place: it front-loads the core action, then covers billing behavior, prerequisites, alternatives, and failure modes. The structure is logical and dense 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 (billing, multi-step process, PENDING state), the description covers all necessary aspects: prerequisite call, user consent, immediateCharge display, targetPlanName, re-check via list_websites, failure modes, and return value (updated websites). Nothing an agent needs is missing.

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

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

The tool has zero parameters, so the schema trivially covers 100% of them. The description adds no parameter details because none exist. Baseline for 0 params is 4, and the description does not detract; it's appropriate.

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

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

The description states a specific action ('Activate every PENDING keyword across the account') with a clear verb, resource, and scope. It also differentiates itself from siblings by naming enable_keyword for a single DISABLED keyword and preview_activate_pending as a prerequisite, so an agent can distinguish it without inspecting other 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 instructs when to call this tool: after preview_activate_pending, with explicit user consent, and never in a loop. It also specifies the alternative (enable_keyword) for a single DISABLED keyword and notes failure conditions (400 when no active subscription or charge fails). No ambiguity remains.

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 thoroughly discloses side effects: trimming/lowercasing/dedup, skipping existing active keywords, resetting disabled ones to pending, activation limited by headroom, no charge for initial activation, and the return of the full updated website. It also notes that later activation may incur charges. This goes well beyond the annotations (readOnlyHint false, destructiveHint false) and gives a complete behavioral model.

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 informative but remains focused, covering all key points in a single paragraph. It uses semicolons effectively and includes necessary digressions about alternative tools and charge implications. It is slightly longer than strictly necessary but avoids redundancy and stays well-organized.

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

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

The description fully addresses the tool's complexity, including state transitions, activation headroom, billing implications, and the output format. It also references related tools (enable_keyword, preview_activate_pending) to place the operation in the broader workflow. No important aspect is missing for an agent to use the tool correctly.

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

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

The schema already provides full coverage of parameters (keywords array with constraints, websiteId UUID). The description adds behavioral semantics beyond the schema, such as how existing keywords are handled (skip active, reset disabled) and the activation logic, enriching the understanding of parameter effects. Though it doesn't introduce new parameter details, the added behavior context justifies above-baseline scoring.

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 keywords to a monitored website') and specifies the resource. It also distinguishes from edit_keyword and mentions the preferred alternative enable_keyword for re-adding disabled keywords, making the tool's unique purpose unambiguous.

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

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

The description gives explicit guidance on when to use this tool versus alternatives: it points out that re-adding disabled keywords should prefer enable_keyword, and advises running preview_activate_pending before activation. It also clarifies that adding is unlimited and explains the activation flow, providing sufficient context for tool selection.

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

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

Beyond the annotations (readOnlyHint false, destructiveHint false), the description discloses quota consumption, refund behavior on failure, precomputed-domain shortcut, and specific HTTP error codes for quota exhaustion and invalid URL. This is rich behavioral context that annotations alone do not provide, and it aligns with the readOnlyHint false because quota consumption is a side effect.

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

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

Four sentences with no redundancy. The main action is front-loaded, followed by usage guidance, quota behavior, and error handling. Every sentence earns its place and there is 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?

The tool has one parameter, an output schema (not shown but present), and clear error conditions. The description covers usage flow, side effects, and failure modes. Nothing an agent needs to call it correctly is missing; the output schema handles return structure.

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

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

The input schema already documents the only parameter 'url' with a clear example, so schema coverage is 100%. The description adds no new meaning about the parameter itself; it mentions 'url' in error conditions but that is not additional semantic detail. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description states a specific verb (scrape) and resource (URL) with a clear deliverable (AI-written business description). It also distinguishes itself from siblings by explicitly positioning it as a drafting/preview step before create_website or update_website, making its purpose unambiguous.

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

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

It explicitly tells the agent when to use this tool ('Use it to draft or preview the text before create_website or update_website') and how to chain the result ('pass the result as their description'). It also clarifies the non-destructive nature and error scenarios, leaving no guesswork about invocation context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only safety is known. The description adds meaningful behavioral details beyond annotations: the default exclusions (REJECTED unless statuses includes it, and low-relevance scores hidden unless includeLowRelevance is true) and the explicit lack of sort/limit/offset. This enriches the agent's understanding of how filtering behaves without contradicting 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 three tight sentences with no wasted words. The core purpose is front-loaded, usage guidance follows, and the constraint (no sort/limit/offset) is stated clearly at the end. Every sentence earns its place, making it highly efficient for an agent to parse.

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

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

For a count tool with 8 optional parameters, 100% schema coverage, and an existing output schema, the description is complete. It covers the tool's purpose, usage guidance, default filtering behavior, and the absence of pagination parameters. Nothing an agent needs to decide whether to call it and what to expect is missing.

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

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

The input schema has 100% parameter description coverage, so the schema already documents each parameter. The description adds value by referencing that the filters are identical to list_mentions and by explaining the default behaviors that affect several parameters (statuses and includeLowRelevance). This provides context beyond the schema's individual field descriptions, though it doesn't detail every 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 opens with a specific verb and resource: 'Count mentions matching the same filters as list_mentions, returning { total } and no rows.' It clearly states what the tool does and differentiates it from list_mentions by noting it returns only the total and no rows, so an agent can distinguish the two without inspecting schemas.

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

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

The description explicitly states when to use it ('Use it for dashboards, to size a triage batch, or to decide whether paging list_mentions is worthwhile') and when not to ('skip this when you fetch rows anyway'), naming the alternative (list_mentions) and the condition that selects it. This leaves no ambiguity about tool selection.

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

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

Discloses side effects beyond the annotations: consumes an AI generation when description is omitted, creates the website, may return 400 on duplicate or slot exhaustion, and stores keywords as PENDING. Also mentions background AI-suggested keywords, providing clear transparency about what happens.

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 comprehensive but somewhat long; the purpose is front-loaded. Some redundancy exists between the omission and passing-your-own-description clauses, but overall it is organized and information-dense without being excessively 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?

Covers creation, error conditions, quota consumption, keyword lifecycle, and related tool usage, making it self-sufficient. The output schema is present, so return details are not required for 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?

While the schema already describes parameters, the description adds crucial behavioral meaning: the description parameter is the scoring context and triggers scraping if omitted; keywords are stored PENDING and promoted via specific tools. This enriches the understanding of how each parameter affects the outcome.

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 adds a website for monitoring across Reddit, Hacker News, X, and Bluesky, with the verb 'add' and resource 'website' being specific. This distinguishes it from siblings like update_website, delete_website, and list_websites.

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

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

Names alternatives such as update_website, analyze_website, list_websites, add_keywords, and activate_pending_keywords, with conditions for when to use them (e.g., after creation if description is missing, or for keyword promotion). Explicitly notes duplicate and slot-limit errors, giving practical guidance on when this tool is appropriate.

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

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

Beyond the destructiveHint annotation, the description adds key behavioral details: no billing effect, no undo, and the return value. This gives the agent a full picture of consequences.

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 longer than a typical one-liner but each sentence adds necessary information (conditions, alternatives, consequences, return). It is well-organized and not redundant, though slightly verbose.

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

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

For a simple single-parameter tool with an output schema, the description fully covers when to use it, what happens, and what to expect in return. No critical information is missing.

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

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

The only parameter (keywordId) is fully described in the schema as 'Keyword ID (UUID)'. The description adds no extra semantic detail, but schema coverage is 100%, so baseline 3 is appropriate.

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

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

Clearly states the action (permanently delete) and resource (one keyword), and explicitly distinguishes from sibling tools by specifying when to use them (disable_keyword for ACTIVE, edit_keyword for SUSPENDED, delete_website for whole site).

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 conditions for use (only PENDING keywords) and names specific alternatives for other statuses, leaving no ambiguity about when this tool should be selected.

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 details the full behavioral impact: immediate removal from list_websites, cessation of matching new mentions, irreversibility (no restore tool), and the exact response format including the 404 error case. This goes far beyond the annotations (destructiveHint) to set complete expectations.

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

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

The description is concise and every sentence carries meaningful information. It efficiently packs purpose, usage guidance, behavioral consequences, and error handling without redundancy or 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?

Covers all necessary context: what happens, when to use, what not to use, irreversibility, and return/error behavior. The presence of an output schema further complements the description, yet the description already covers the key aspects thoroughly.

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 add further meaning to the websiteId parameter beyond the schema's own description ('Monitored website ID (UUID)'). Since schema coverage is 100% and the parameter is self-explanatory, the baseline score of 3 applies.

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

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

The description clearly states the tool's action ('Stop monitoring a website (soft delete)') and specifies the resource (website). It also distinguishes it from related sibling tools like disable_keyword and delete_keyword, making its purpose unambiguous.

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

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

Explicitly states when to use the tool ('Use this only when the whole site should go') and contrasts it with alternatives (disable_keyword, delete_keyword), including the instruction to confirm with the user first. This provides clear guidance on when to select this tool over 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?

The description discloses several behavioral nuances beyond the annotations: billing implications (keeps paid slot until end of cycle, re-enabling in same cycle is free), reversibility, idempotency (calling on already disabled returns unchanged), and the distinction for pending keywords. This aligns with the destructiveHint annotation (state modification) but clarifies the reversible nature, so no contradiction.

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

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

The description is somewhat lengthy but every sentence conveys essential information (billing, reversibility, idempotency, contrast with delete). It is well-structured with clear statements, though it could be slightly more concise without losing critical details.

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

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

Given the tool's simplicity (one parameter), the description provides complete context: it covers the primary action, side effects (billing), edge cases (pending keywords, already disabled), and the relationship to sibling tools (enable_keyword, delete_keyword). No important operational aspect is missing.

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

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

The schema already provides 100% coverage for the sole parameter (keywordId as UUID). The description does not add extra semantic meaning to the parameter itself beyond the schema, though the context of 'keyword' is implied. This meets the baseline but does not exceed 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 tool's action: 'Stop monitoring one keyword' and specifies the effect (sets it DISABLED, stops matching new mentions). It also differentiates from sibling tools by explicitly contrasting with delete_keyword and mentioning enable_keyword.

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

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

It provides explicit guidance on when to use this tool vs. alternatives: 'Use delete_keyword instead for a PENDING keyword you never want.' It also implies usage for temporary suspension and mentions reversibility via enable_keyword, giving clear decision 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 goes beyond annotations (destructiveHint:true, readOnlyHint:false) by detailing exact behaviors: unlimited edits, re-grading for noise, status transitions (ACTIVE stays ACTIVE, others go ACTIVE if slot free else PENDING), and duplicate handling. This level of detail is highly transparent.

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

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

The description is dense but well-organized, covering multiple important aspects in three sentences. It is slightly long but every sentence adds critical information, so it remains efficient.

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

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

Given the tool's complexity (status transitions, billing implications, uniqueness checks), the description covers all key behaviors the agent needs to know. It explains the impact on paid slots, re-grading, and error conditions, making it fully sufficient for correct invocation.

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

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

Although the schema already covers keywordId and value with descriptions, the tool description adds meaningful context: 'keeping its ID' clarifies the ID is preserved, 'case-only change is a no-op' explains value normalization, and 'value already on the website returns 400' warns of uniqueness constraints.

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

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

The description clearly states the tool's purpose: 'Change a keyword's text in place, keeping its ID and any paid slot.' It distinguishes itself from add_keywords by explicitly noting 'reword instead of adding a variant with add_keywords.'

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

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

The description provides explicit when-to-use guidance: 'Use this to fix a SUSPENDED keyword the grader rejected, or to reword instead of adding a variant with add_keywords.' It also clarifies edge cases like case-only changes being no-ops and duplicate values returning 400.

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 only basic safety flags (readOnlyHint=false, destructiveHint=false). The description enriches this with crucial behavior: conditional immediate activation, charging behavior, state transition to PENDING then ACTIVE, the 400 error without subscription, and unchanged handling of already-ACTIVE keywords. 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 dense paragraph but every sentence adds value, covering behavior, alternatives, and edge cases. It is front-loaded with the core action and slightly verbose but not bloated.

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 (conditional state transitions, billing implications) and presence of an output schema, the description covers all needed aspects: when it activates immediately, when it goes pending, what to re-check with get_website, error conditions, and alternatives. Nothing an agent needs is missing.

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

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

The single parameter keywordId is fully documented in the schema (UUID), with 100% schema description coverage. The description does not add meaning beyond the schema, which is acceptable given the schema's sufficiency, so baseline 3 applies.

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

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

The description clearly states the tool re-activates a disabled keyword, with explicit conditions for immediate activation vs pending. It distinguishes itself from siblings activate_pending_keywords and add_keywords by name, so an agent can easily tell them apart.

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

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

It explicitly names alternatives (activate_pending_keywords for bulk pending, add_keywords for new keywords) and recommends preview_keyword_billing for cost. It also explains the scenario-dependent behavior, leaving no ambiguity about when to use it.

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

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

The description discloses that the tool generates and stores missing data on first call, making later calls instant reads—a significant behavior not captured by annotations. It also clarifies the return behavior for unknown IDs (null, not 404). These details go well beyond the annotation hints and provide essential operational context.

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

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

The description is concise and front-loaded with the core action, followed by behavior, usage guidance, and return semantics. Each sentence serves a purpose, and the length is appropriate for the complexity. It could be slightly trimmed but is efficient.

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

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

Given the tool's complexity (one parameter, generation behavior, storage, slow performance, prerequisites), the description covers all necessary aspects: when to use, what to expect, return values, and the website description prerequisite. The output schema exists (though not shown), so return details are covered. The description is complete for an agent to decide and invoke correctly.

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

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

The single parameter mentionId is fully described in the input schema (UUID from list_mentions), and the description does not add extra parameter-level semantics beyond what's already provided. Since schema coverage is 100%, the baseline of 3 is appropriate; the description adds no new parameter details, but it does not need to.

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: retrieving AI relevance reasoning, tags, and a drafted reply for a single mention. It also distinguishes itself from siblings by explicitly mentioning update_mention_status and list_mentions, making the resource and action 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?

It explicitly provides when to use ('when a score looks wrong or before update_mention_status on a borderline lead') and when not to use ('not across every row of list_mentions, since generation is slow'). It also mentions a prerequisite (website must have a description) and the consequence if missing. This is comprehensive 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 the read-only nature ('Read-only') and explains the minInterval/availableCadences constraint behavior. While the annotations already indicate read-only, the description adds meaningful detail about the floor constraint and the 'never reported below the floor' behavior.

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

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

The description is compact and well-structured, but slightly repetitive with the 'cadenceMinutes is never reported below the floor' sentence appearing twice in essence. Still, it is efficient and front-loads 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?

The description provides sufficient context for a no-parameter read operation: what it returns, the constraint behavior, and when to call it. The output schema exists, so return values need not be spelled out. Minor deduction for the slight redundancy but overall complete.

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

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

The tool has zero parameters, so the description cannot add parameter-level detail. With no parameters, a baseline score of 3 is appropriate as the schema coverage is complete and there is nothing else to explain.

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

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

The description clearly states the tool retrieves the account's email-alert settings and enumerates the exact fields returned. It distinguishes itself from the sibling update_alert_settings tool by focusing on the 'get' 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 explicitly instructs when to use this tool: 'Call it before update_alert_settings to pick a value from availableCadences, and after it to confirm what applied.' This provides clear contextual guidance relative to the sibling tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds behavioral details about error responses (404 for non-existent or account-mismatched website, 400 for non-UUID), giving extra transparency 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 sentence that packs multiple pieces of information (purpose, usage guidance, parameter source, error details). While not overly long, it could be slightly more scannable. Still, every sentence earns its place.

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

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

The description gives a good overview of what is returned ('full keyword list and statuses') and mentions error cases, but does not detail the output structure. Since an output schema exists, this is acceptable; the description provides sufficient context for calling the tool.

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

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

The schema description covers the parameter completely, but the tool description adds valuable context by noting that websiteId 'comes from list_websites or create_website'. This extra semantic meaning helps the agent correctly source the parameter.

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

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

The description states a specific verb ('Get') and resource ('monitored website by ID'), and explicitly mentions the included keyword list and statuses. It also distinguishes this tool from list_websites by specifying the use case, making it clear which tool to pick.

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 tells when to use this tool ('re-check keyword statuses after add_keywords, enable_keyword, or activate_pending_keywords') and when not to ('use list_websites instead when you do not have the ID yet or want every site'). This provides unambiguous usage 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 behavioral semantics beyond annotations, such as the meaning of 'limit -1 means unlimited' and the fact that only 'edit_keyword' counts toward the allowance. This reveals how the metric behaves without contradicting the readOnlyHint.

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

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

The description is well-structured: the core purpose is stated first, followed by clarifications and alternative guidance. It is concise while providing necessary context 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 simplicity (no params, single output object), the description covers the output format, value semantics, and relevant use cases, making it complete for an agent to invoke correctly.

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

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

The tool has zero parameters, so there is nothing to describe. The baseline for no parameters is 4, and the description does not need to add 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 tool's purpose: 'Get the monthly keyword-edit allowance for the account as { limit, used, remaining, unlimited }'. It differentiates from sibling tools by noting it is not a capacity or billing preview and not for counting active keywords, making its purpose unambiguous.

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

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

Explicit guidance is provided: 'Every current plan reports unlimited, so there is no need to check it before edit_keyword; it remains for clients that budget edits.' It also names alternatives (preview_keyword_billing, preview_activate_pending, list_websites) for different needs, making when-to-use clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial non-obvious behavior: the REJECTED default exclusion, the below-min-score (30) hiding that overrides even scoreBuckets=LOW/VERY_LOW, pagination semantics (offset while offset < total), and the ingestion-time vs publish-time distinction for from/to. 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?

Long, but every sentence earns its place for an 11-parameter tool with tricky defaults. It is front-loaded with the core purpose, then defaults, return shape, sorting, and sibling routing in a logical order. Slightly denser than strictly necessary but well organized.

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

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

Comprehensive for a complex read tool: return shape matches the output schema, default filtering behaviors are fully disclosed, pagination is explained, the scoreBuckets/includeLowRelevance interaction is clarified, and sibling routing is explicit. Given the output schema exists, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful cross-parameter semantics the schema alone cannot convey — notably that scoreBuckets=LOW/VERY_LOW only shows when includeLowRelevance is also true, and the 30-default minimum. This is genuine added meaning beyond the per-parameter 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?

States a specific verb+resource+scope: 'List mentions matched for this account across Reddit, Hacker News, X, and Bluesky.' It details the returned fields (source, keyword, status, content, relevanceReason, aiReplySuggestion) and names the sibling tools it is not (count_mentions, explain_mention, update_mention_status), so an agent can distinguish it without opening any schema.

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

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

Explicitly routes to alternatives: 'Use count_mentions for the number alone, explain_mention for one mention's reasoning, and update_mention_status to triage.' It also gives selection guidance within the tool itself — 'Sort RELEVANCE for the best leads, RECENT for what is new' — leaving nothing to inference.

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

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

The annotations declare readOnlyHint=true, implying no state changes, but the description states that reading 'promotes any PENDING keyword that fits the plan's free headroom to ACTIVE'. This is a direct contradiction, as promotion modifies state.

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

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

The description is mostly concise but includes explanatory notes about promotion and 'quiet inbox' that, while informative, go slightly beyond the core purpose. Still well-structured and not 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 no parameters and a clear output description (websites with keywords and statuses), the tool is adequately described. Some details about output structure or pagination are absent, but not critical for basic 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?

The schema has no properties, and the description mentions no parameters. Since schema coverage is 100% (empty), the baseline of 3 applies; there is no parameter info to add.

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 monitored websites with their keywords and statuses, and explicitly distinguishes it from get_website. This provides a precise purpose.

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

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

The description explicitly says 'Call this first' and explains that most other tools need a websiteId or keywordId from it. It also advises using get_website when holding an ID, offering clear selection 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 states 'without changing anything,' which matches the readOnlyHint annotation, and it explains the meaning of specific output values (e.g., immediateCharge 0 with isUpgrade false means free). This goes slightly beyond the annotation by providing interpretive context, though it does not mention potential side effects or error conditions beyond the read-only guarantee.

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 slightly longer than necessary but every sentence adds value: it states the purpose, the lack of inputs, the computation logic, the output fields, and usage distinctions. It is front-loaded with the most critical information and does not contain redundant fluff.

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

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

The description fully covers the tool's context: when to use it, what it computes, what the output fields mean, and how it differs from the sibling preview_keyword_billing. Since an output schema exists, the description need not enumerate all return fields, but it still provides valuable interpretation of key output semantics.

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

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

The tool takes no parameters (schema coverage 100%), so there is nothing to explain. Per the rubric, 0 parameters receives a baseline score of 4. The description correctly omits any parameter details, and no additional clarification is needed.

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

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

The description clearly states the tool's purpose: previewing the billing impact of activating pending keywords. It uses a specific verb ('preview') and resource ('billing impact of activate_pending_keywords'), and explicitly contrasts it with the sibling tool preview_keyword_billing, making the distinction 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 gives explicit usage guidance: 'Use this right before activate_pending_keywords' and 'Use preview_keyword_billing instead to price an arbitrary keyword count, for example before add_keywords or enable_keyword.' This clearly tells the agent when to use this tool versus the alternative, leaving no 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'without changing anything.' It adds value by specifying the exact return shape (same as preview_activate_pending) and clarifying the parameter semantics. This goes beyond the annotation baseline but doesn't introduce new behavioral caveats, so a 4 is appropriate.

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 serves a purpose: the first states the core function, the second clarifies the parameter, the third lists the return fields, and the last gives usage guidance. Information is front-loaded, and there is no redundancy or fluff.

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

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

For a tool with a single parameter, a clear schema, an output schema, and annotations covering safety, the description fully equips the agent: it explains the parameter's meaning, the return shape, and when to use it vs. the alternative. Nothing needed for correct invocation is missing.

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

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

The schema already provides a clear description of desiredKeywordCount (absolute count, not increment). The tool description adds an operational hint: 'count the ACTIVE keywords from list_websites and add the new ones.' This provides practical guidance beyond the schema, but since schema coverage is 100%, the baseline is 3; the extra example lifts it to 4.

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

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

The description clearly states the tool's purpose: preview the plan and price for a chosen total of active keywords without modifying anything. It uses a specific verb (preview) and resource (keyword billing) and explicitly distinguishes itself from the sibling preview_activate_pending, making it easy to identify the right tool.

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

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

It explicitly states when to use this tool ('for what-if pricing before add_keywords or enable_keyword') and when to use an alternative ('use preview_activate_pending instead for the exact cost of activating the keywords already PENDING'). This direct routing to a sibling tool eliminates 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?

Beyond the destructiveHint annotation, it discloses specific side effects: both settings are replaced, omitting cadenceMinutes resets to fastest allowed, values faster than plan floor are silently raised, and validation returns 400. 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?

Every sentence provides necessary information—purpose, validation rules, side effects, usage guidance, and output. The structure is logical and free of fluff.

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

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

The description fully covers what the tool does, how to use it, expected behavior, error conditions, and return value. It also references the appropriate sibling tool for complementary actions, making it self-contained for an agent.

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

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

Schema coverage is 100%, but the description adds critical meaning: allowed cadence values, plan floor behavior, reset semantics when omitted, and requirement that enabled is always passed. This goes well beyond the schema.

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

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

The description clearly states the tool's function: turning mention email alerts on/off and setting the digest frequency. It uses a specific verb and distinguishes it from sibling tools like get_alert_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 explicitly directs users to get_alert_settings for available cadences before and confirmation after, and explains when to use this tool (e.g., passing current value when only toggling enabled).

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, destructiveHint false), so the description carries the full behavioral burden. It fully discloses reversibility, side effects of REJECTED on default lists, and the reviewedAt timestamp lifecycle. 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, both dense with information, with the core purpose front-loaded. Every clause earns its place—no filler or repetition of schema fields. The long second sentence is acceptable given the amount of behavioral context it packs.

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 side effects and multiple status transitions, the description covers all essential operational details: reversibility, timestamp behavior, effect on lists, source of the ID, and the recommendation to verify with explain_mention. Output schema exists, so return format is already covered.

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

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

Schema coverage is 100% but the description adds significant value beyond the enum definitions: it explains the downstream consequences of each status (REJECTED hides from default lists, NEW returns to inbox) and the source of mentionId. This transforms dry schema into actionable 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 opens with a specific verb+resource ('Set one mention's triage status') and immediately distinguishes the three statuses. It clearly differentiates from siblings like list_mentions and explain_mention by focusing on the single-mention state change.

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

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

Explicitly states when to call explain_mention (when score looks off), when to avoid approving (without reading), and describes how REJECTED affects default list_mentions/count_mentions results. Also tells the agent where mentionId comes from (list_mentions), leaving no ambiguity about 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 already mark destructiveHint, and the description adds field-level behavior such as clearing via empty string and preserving omitted fields. It also discloses the scoring-context effect, though it does not explicitly state irreversibility beyond the annotation.

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 compact and well organized, with each sentence serving a purpose: what updates, partial-update semantics, scoring context, and limitations. No unnecessary wording.

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?

Provides enough context to call correctly: partial update behavior, clearing semantics, scoring implications, and unsupported fields. Return value is stated, and the output schema exists, so no further detail is required.

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 all three parameters with clear descriptions, but the tool description adds important semantics: only passed fields change and empty description clears. This goes beyond the schema's basic field 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?

States a specific action: updating a monitored website's display name and/or description. It distinguishes itself from sibling tools by explicitly noting that URL and keywords cannot be changed and pointing to analyze_website for drafting descriptions.

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

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

Gives explicit when-to-use guidance: partial updates, omitted fields keep values, empty description clears it, and mentions not rescored. It also names alternatives for keyword changes, making the choice clear.

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