RedReplier

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

Discloses substantial behavior beyond the annotations: normalization (trim/lowercase/de-dup), state machine transitions (PENDING, ACTIVE, DISABLED reset to PENDING), the free-headroom auto-activation and billing consequence, and that adding is unlimited with no charge. Annotations only cover the mutation/safety profile, so this adds real value. Slight gap: no mention of auth/permission requirements or rate limits, which is minor here.

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

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

Front-loaded with purpose and alternatives, and every sentence carries distinct operational information (normalization, state transitions, billing, return shape). It is long, and the billing/upgrade sentences could be compressed, but nothing is redundant 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 the full lifecycle an agent needs for a non-obvious multi-state mutation: what is skipped, what resets, what activates for free, what stays inert, and what the call returns. Output schema exists but the explicit return note prevents a common misread.

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

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

Schema description coverage is 100% and the descriptions already state trimming, lowercasing, de-duplication and the 255-char limit, so the prose largely restates the schema. Baseline 3 applies since the schema carries 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?

Specific verb + resource ('Add keywords to a monitored website'), immediately situated against siblings by naming enable_keyword and edit_keyword as the alternatives for their respective cases. An agent can distinguish this from every other keyword tool without opening a schema.

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

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

Explicit routing: prefer enable_keyword when re-enabling a DISABLED keyword, and use edit_keyword to reword an existing one. It also explains what preview_activate_pending is for, giving a clear when-to-use-this-instead map.

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?

Annotations only declare the safety profile (readOnly=false, destructive=false, openWorld=false); the description goes well beyond that, disclosing the 400 on duplicates, record revival after delete_website, the quota cost of omitting description, the degraded null-description path and its UNSCORED consequence, background AI keyword suggestions, and the 400 when no slots remain.

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

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

Purpose and platform scope are front-loaded, and each sentence carries operational weight (duplicates, quota, PENDING promotion, slot limits). It is dense and one long block rather than broken into scannable structure, but little is wasted.

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

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

For a create tool with a full output schema and 100% param coverage, the description fills the remaining gaps: failure modes, quota interactions, background side effects, and quota-driven 400s. Nothing an agent needs to call this 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 real consequence-level meaning beyond the schema: omitting description triggers a URL scrape that spends one AI generation and can fail into a null-description site, and keywords are PENDING rather than active. It does not explain name, which the schema covers anyway.

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

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

Opens with a specific verb+resource (add a website to monitor) and names the four platforms covered, which no sibling tool matches. An agent can distinguish it from get_website, update_website, or add_keywords without opening a schema.

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

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

Explicitly states when this is the right tool and routes the agent elsewhere when not: set a description via update_website or analyze_website, promote PENDING keywords via list_websites or add_keywords. It also spells out the duplicate-400 and revive-after-delete conditions, which are precisely the kind of 'when not' guidance that prevents wrong calls.

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

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

Annotations only declare destructiveHint=true and readOnlyHint=false; the description goes well beyond by disclosing the status precondition, the exact 400 error and its message on violation, the fact that there is no billing effect and no undo, and the return payload. This is unusually rich behavioral context for a deletion tool.

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

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

Four tight sentences, front-loaded with the destructive scope and status precondition, then routing, then rationale, then return shape. Each sentence carries unique information; nothing is redundant with the schema or annotations.

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

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

For a single-parameter destructive tool, everything an agent needs is present: eligibility, failure mode, sibling routing, side effects, and return value. An output schema exists, so the brief return mention is sufficient rather than 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?

There is one parameter with 100% schema description coverage ('Keyword ID (UUID)'), so the schema already carries the semantics. The description adds nothing about the ID's origin or format, making it a baseline 3 rather than a value-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?

Names a specific verb and resource ('Permanently delete one keyword') and immediately scopes it to a single status, which is what separates it from disable_keyword, edit_keyword, and delete_website. An agent can route correctly 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 states the qualifying condition (only PENDING keywords), names three alternatives with the exact status each applies to, and adds a positive-use rationale (unbilled pending keywords inflate a plan upgrade). When-to-use, when-not-to-use, and alternatives are all covered.

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 only say it is a non-destructive write; the description goes much further, disclosing that activation is immediate when the plan fits or the slot is held, that it otherwise goes PENDING until upgrade, that the tool never charges, and that an already-ACTIVE keyword is returned unchanged. That is exactly the behavioral context annotations cannot carry.

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

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

Dense and front-loaded, with the alternative tools and the failure mode at the end. Every sentence carries information, though the activation-state clause is packed tightly enough to read as one run-on rather than cleanly separated branches.

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 operation, its alternatives, the billing implication, the subscription failure mode, and even the idempotent return behavior for an ACTIVE keyword. With an output schema present, nothing further is required of the description.

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

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

Schema coverage is 100% for the single keywordId parameter, so the schema already documents the input. The description adds state semantics (must be DISABLED, ACTIVE is a no-op) but no format or ID-syntax detail beyond the schema. Baseline 3 applies.

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

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

States a precise verb and resource: 'Re-activate one DISABLED keyword.' The state qualifier (DISABLED only) distinguishes it cleanly from add_keywords, disable_keyword, and edit_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?

Names two explicit alternatives with the condition that selects each: add_keywords for a keyword that does not exist yet, preview_keyword_billing to see upgrade cost. Also states the subscription precondition (400 without an active subscription).

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 this a safe read (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description nonetheless adds real behavioral context the annotations cannot express: the enumerable statuses and the 404 (not found / other account) and 400 (non-UUID) failure semantics. It does not mention pagination or response shape, but the output schema covers returns.

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 tight sentences, front-loaded with the action and payload, then routing, then provenance, then error behavior. No filler and every clause carries operational 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?

Complete for a single-parameter read tool: identity, routing to siblings, ID provenance, failure modes, and status vocabulary are all covered, and the return shape is left to the existing 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 100%, so baseline is 3, but the description goes beyond the schema by naming both sources of the ID (list_websites or create_website) and tying a malformed value to the 400 error, which the schema does not state.

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 ('Get one monitored website by ID') and names the payload it returns (full keyword list and statuses). It explicitly distinguishes itself from the sibling list_websites, so an agent can route without opening either schema.

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

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

Gives explicit when-to-use ('re-check keyword statuses after add_keywords or enable_keyword') and when-not ('use list_websites instead when you do not have the ID yet or want every site'). It also states where websiteId comes from, removing the main prerequisite 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 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?

Consistent with the readOnly/non-destructive annotations and adds real context beyond them: 'without changing anything', 'takes no input', and the important boundary that 'The upgrade itself happens in the RedReplier app'. It also interprets a return condition (immediateCharge 0 with isUpgrade false means current plan already covers them), which is behavioral value not present 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?

Front-loaded with the core action and constraint, then adds a dense but useful return-field list and a closing alternative-tool pointer. The nine-field enumeration overlaps substantially with the existing output schema, which is slight redundancy, but the surrounding interpretive 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?

For a no-input, read-only pricing preview with an output schema present and annotations covering safety, the description supplies everything an agent needs: what it costs, what plan it targets, that nothing changes here, and where the actual upgrade happens.

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?

Zero-parameter tool, so the baseline is 4. The description confirms 'Takes no input', which is consistent with the empty schema, but adds nothing further since there are no parameters to disambiguate.

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

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

Specific verb ('preview') + resource ('activating pending keywords') with the exact scope defined: pricing the plan needed for keywords committed this cycle plus every PENDING keyword. It clearly distinguishes itself from the sibling preview_keyword_billing by name.

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 usage: 'Use preview_keyword_billing instead to price an arbitrary keyword count, for example before add_keywords or enable_keyword.' This gives both the alternative and concrete trigger scenarios, so an agent knows exactly when to pick this tool.

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

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

Annotations already declare 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.