RedReplier

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

The description discloses a significant side effect that annotations do not cover: charging an upgrade if pending keywords exceed the current plan. It also states the promotion behavior (free for what fits) and the return value, giving the agent a complete behavioral picture.

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

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

The description is three sentences with no wasted words. The core purpose is front-loaded, and each sentence adds distinct value: what it does, how billing works, and what to do first.

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

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

Given that there are no parameters and an output schema exists, the description covers all necessary context: the activation behavior, the potential charge, the preview recommendation, and the return value. An agent has enough information to invoke this tool correctly.

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

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

The tool has zero parameters, so the schema is exhaustive and there is nothing for the description to add about parameter semantics. The baseline of 4 applies because no parameter documentation is needed.

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

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

The description states a specific action ('Activate PENDING keywords') and clearly distinguishes this batch activation from sibling tools like enable_keyword or add_keywords. It also explains the outcome (returns updated websites), making the tool's role 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 explicitly tells the agent to use preview_activate_pending first to see the cost, which is a direct usage guideline and alternative routing. It also implies this tool is the actual activation step, making the relationship to the preview sibling 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 only indicate that the tool is not read-only, not open-world, and not destructive. The description adds meaningful behavioral context: new keywords start as PENDING, are auto-promoted to ACTIVE when they fit the plan, and excess keywords remain PENDING until activation. It does not cover edge cases like duplicate handling, but the core state-transition behavior is well disclosed.

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 front-loaded with the primary action, followed by essential behavioral details in a clear sequence. Every sentence earns its place, and there is no redundant restatement of the tool name or schema fields.

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 small parameter surface, 100% schema coverage, and presence of an output schema, the description is complete enough for an agent to call the tool correctly. It explains the critical plan-dependent behavior and directs the agent to the relevant sibling tool for excess keywords, leaving no major gap.

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

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

The input schema already documents both required parameters (websiteId and keywords) with descriptions, giving 100% schema coverage. The description does not add parameter-level detail, but it does not need to because the schema fully covers semantics. This meets the baseline for schema-driven parameter clarity.

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

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

The description uses a specific verb and resource — 'Add keywords to a website' — and then clarifies the lifecycle (PENDING → ACTIVE) so the tool is clearly distinguished from siblings like delete_keyword, edit_keyword, and activate_pending_keywords. It states the core action and its immediate behavioral consequence.

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 clearly names the follow-up/sibling tool activate_pending_keywords for keywords that remain PENDING, and explains the plan constraint that determines when that tool is needed. This gives an agent an explicit decision rule: adding keywords is the right move for creating keywords; activation is handled separately.

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 sparse, but the description adds valuable behavior beyond them: it scrapes a remote URL, runs AI generation, and consumes AI quota. This cost/side-effect disclosure is meaningful even though readOnlyHint is false. It doesn't mention error behavior or rate limits, but the core behavioral traits are covered.

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

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

The description is two efficient sentences: the first states the core action and result, the second adds workflow context and a resource-consumption warning. Every sentence earns its place with no redundancy.

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

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

With one required parameter, an output schema, and annotations present, the description covers the essential behavior, the workflow context, and the notable side effect (AI quota consumption). Nothing critical is missing for an agent to select and invoke this tool correctly.

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

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

Schema coverage is 100% and the single url parameter is already described as 'Website URL to analyze.' The description adds no new parameter-level detail about format, protocol, or constraints, so the baseline score of 3 is appropriate.

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

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

The description states a specific action ('Scrape a URL') and the produced result ('generate an AI description of the business'), clearly distinguishing it from website CRUD siblings like get_website, create_website, and update_website.

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 clear context: it is useful to preview or seed the description before creating a website. It doesn't explicitly list when not to use it or name alternatives, but the intended workflow is evident from the surrounding sibling tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description does not contradict them. It adds the key behavioral detail that this tool counts but does not return rows, which is helpful. It does not discuss output format or potential rate limits, but an output schema exists, lowering the burden.

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

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

A single well-structured sentence front-loads the operation and scope, then adds the no-rows caveat and use cases with no filler. Every word earns its place.

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

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

Given the presence of an output schema and safety annotations, the description covers the essential behavior, use cases, and the relationship to list_mentions. The only gap is that parameter semantics are not self-contained, instead depending on the sibling tool's filter definitions, which is acceptable but less complete for standalone use.

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

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

Schema description coverage is only 38%, so the description must help. It does so by pointing to list_mentions and asserting these are the same filters, which tells the agent to look there for parameter semantics. However, it does not describe individual parameters like statuses, scoreBuckets, or includeLowRelevance, leaving some reliance on the sibling's documentation.

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

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

The description states a specific verb and resource: 'Count mentions matching the same filters as list_mentions'. It explicitly differentiates from the sibling list_mentions by adding '(without returning the rows)', so an agent can immediately distinguish the two tools 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?

The description gives clear context: it is useful for pagination and dashboards, and it names list_mentions as the tool that returns rows. While it does not spell out a hard when-not-to-use rule, the contrast with list_mentions is stated clearly and sufficiently implies when the count version is preferred.

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

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

Adds meaningful side-effect detail beyond annotations: keywords are initially PENDING and only become ACTIVE after activation, the first website seeds keywords, and omitting description triggers scraping/AI generation. No contradiction with readOnlyHint=false.

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

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

Three sentences with no filler; the most important creation semantics are front-loaded before the caveats. 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?

Covers success outcome, pending/active lifecycle, the follow-up call, first-account edge case, and default behavior for an omitted description. With an output schema available, nothing needed for a correct call is missing.

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

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

Schema description coverage is 100%, and most behavioral parameter details (PENDING keywords, description skipping scraping/AI) already appear in the input schema. The description reinforces them and adds the account-level seeding behavior, but doesn't materially expand parameter meaning.

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

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

States a specific verb ('Add') and resource ('website to monitor') plus the four platforms monitored. Clearly distinguishes from sibling update_website/delete_website/list_websites by naming the creation entry point.

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

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

Gives clear sequencing context: keywords begin PENDING and require activate_pending_keywords afterwards, and the first website seeds keywords from the shared feed. It doesn't explicitly contrast with add_keywords, but the creation context and follow-up call make appropriate 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 destructiveHint=true, but the description adds the irreversibility ('Permanently') and the state constraint (only PENDING). This goes beyond the structured metadata without contradicting it.

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, front-loaded with the core action, and wastes no words. The second sentence adds valuable routing information without verbosity.

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

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

For a simple single-parameter destructive tool with an output schema and clear annotations, the description fully covers what the agent needs: what it does, when it's allowed, and what to use instead in other states.

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 already fully documented in the schema with type and format (UUID). The description adds no additional parameter-level detail, so the schema carries the burden; baseline of 3 is appropriate.

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

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

The description clearly states the verb (delete), the resource (keyword), and the permanent nature of the operation. It distinguishes itself from sibling tools like disable_keyword and edit_keyword by explicitly naming them as alternatives.

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: only PENDING keywords can be deleted, while ACTIVE keywords should be disabled and SUSPENDED ones edited. This directly tells the agent when to use this tool and when to choose an alternative.

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 this as destructive, so the description's 'soft delete' clarification adds meaningful behavioral nuance beyond the annotation. The additional note that keywords cease matching new mentions provides useful side-effect transparency.

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

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

The description is a single tight sentence that front-loads the main action, adds the soft-delete qualifier, and provides the most important consequence. There is no redundant or filler language.

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

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

For a simple tool with one parameter and an output schema, the description covers the essential behavioral information: what happens to the website and what happens to its keywords. No critical context is missing.

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

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

The input schema already fully documents websiteId as a 'Monitored website ID (UUID)' with 100% coverage. The description does not add new parameter-level detail, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Stop monitoring') and resource ('a website'), and clarifies it is a soft delete. It also distinguishes the effect from related tools by stating that keywords stop matching new mentions.

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 conveys when to use the tool: when you want to stop monitoring a website without a hard delete. However, it does not explicitly reference alternatives such as update_website or delete_keyword, so the usage guidance is more implied than stated.

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

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

Beyond the annotations, the description adds meaningful behavioral context: disabling is unlimited, immediate, and any price reduction is deferred to the end of the billing cycle. It does not contradict the destructiveHint annotation, since it clearly frames the action as a status change rather than deletion.

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

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

The description is two short sentences with no redundant wording. The primary action is front-loaded, and the billing detail is a valuable addition without bloating the text.

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 tool with an output schema, annotations, and a clear state change, the description covers the essential behaviors: what happens immediately and what happens with billing. Nothing critical is missing for an agent to call this tool correctly.

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

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

The schema already documents keywordId as a UUID string with 100% coverage. The description adds no extra meaning about the parameter itself, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action: 'Stop monitoring a keyword' and explicitly defines the resulting state as DISABLED. This distinguishes it from sibling tools like delete_keyword and 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?

The description implies when to use this tool: when you want to stop monitoring a keyword while keeping it in a disabled state. However, it does not explicitly mention alternatives like delete_keyword or enable_keyword, nor does it provide when-not-to-use guidance.

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

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

The description goes well beyond the destructiveHint annotation by disclosing specific consequences: editing a live keyword counts against the monthly change allowance, the new value is re-graded, and any paid slot is preserved. This gives an agent an accurate model of the tool's behavioral and side effects.

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

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

The description is brief and front-loaded with the core purpose, followed by three concise, high-value behavioral statements. Every sentence earns its place and no information is repeated or padded.

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

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

For a simple two-parameter mutation with an output schema and annotations, the description is complete. It covers the operation's purpose, the key cost and side-effect considerations, and points to the related allowance tool. Nothing essential for a correct invocation is missing.

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

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

Schema description coverage is 100%, with both keywordId and value already documented. The description adds minimal parameter-specific meaning beyond the schema, noting that the new value is re-graded, but it does not explain keywordId semantics beyond what the schema already provides.

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

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

The description states a specific verb and resource: 'Change a keyword's text.' This clearly distinguishes edit_keyword from sibling tools like delete_keyword, enable_keyword, and disable_keyword, which target status or existence rather than the keyword's textual value.

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

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

The description provides clear context for when the tool is used: editing a keyword's text, with different cost implications for suspended vs live keywords. It does not explicitly name alternatives or exclusion cases, but it references keyword_change_usage for allowance tracking, which gives useful guidance without being fully explicit.

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

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

The description discloses the conditional state transition ('ACTIVE' vs 'PENDING with upgrade required'), which goes well beyond the annotations that only indicate a non-read, non-destructive operation. It explains what happens under different plan conditions, giving agents realistic expectations about side effects and required follow-up actions. This is valuable behavioral context not available anywhere else.

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

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

The description is a single well-organized sentence that front-loads the core action and resource, then explains the conditional outcome. Every clause adds essential information, and there is no redundancy or filler. It is optimally concise for the complexity of the behavior.

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 explains the tool's behavior for a simple one-parameter operation. It covers both possible outcomes and their implications. The presence of an output schema means return values do not need to be described, and annotations handle the basic mutability/safety context. Nothing essential is missing for an agent to decide when to call this tool and what to expect.

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 single parameter 'keywordId' with its type and description. The tool description adds no additional parameter-specific meaning, but none is needed because the schema is complete. The baseline of 3 applies here.

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

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

The description uses a specific verb ('Re-activate') and identifies the exact resource ('a disabled keyword'), making the action unambiguous. It also explains the state outcome (ACTIVE or PENDING), which distinguishes it from sibling tools like disable_keyword, add_keywords, or edit_keyword. The purpose is immediately clear without needing to inspect the schema.

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

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

The description clearly states when to use the tool: when re-activating a disabled keyword. It provides the context that the result depends on plan fit, so an agent can predict the outcome. However, it does not explicitly mention alternatives or state when not to use it (e.g., for active keywords), though this is strongly implied.

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

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

The description goes beyond the all-false annotations by explicitly disclosing the 'lazily generate' behavior, meaning this tool may trigger computation or creation rather than only reading stored data. It does not detail caching behavior, latency, or potential costs, but the key non-read behavior is visible.

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, tightly written sentence that front-loads the main action and scopes it to a single mention. Every part adds meaning, with no wasted words or repetition of schema fields.

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 one-parameter tool with an output schema, the description covers the core purpose, scope, and the notable lazy-generation behavior. It does not mention edge cases like invalid mention IDs or when to choose this over siblings, but the low complexity and existing schema make this acceptable.

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

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

Schema coverage is 100%: the only parameter, mentionId, is fully documented with its type and format. The description adds only the 'single mention' scope and does not replicate or extend parameter details, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: retrieving (and lazily generating) the AI relevance reasoning and tags for a single mention. It uses a specific verb and resource, and the 'why it was scored the way it was' framing distinguishes it from listing or updating mention 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?

Usage context is implied: use this when you need the reasoning or tags behind a single mention's score. However, no explicit alternatives, conditions, or when-not-to-use guidance are provided, leaving the agent to infer the right scenario.

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 tool's non-mutating safety profile is covered. The description adds useful context by listing the returned setting fields, but it does not discuss authentication, errors, or other behavioral traits. This is consistent with the annotation, 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 a single, front-loaded sentence that wastes no words. It states the action first, then lists the specific pieces of information returned, making it easy to scan and 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 zero-parameter, read-only tool with an output schema and consistent annotations, this description is complete enough for an agent to select and invoke the tool correctly. It names the resource and the exact returned attributes, leaving no meaningful gap for this complexity level.

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

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

The tool has zero parameters, so the input schema is empty and the description need not explain parameter usage. Per the baseline for zero-parameter tools, this is adequate; the description's focus on return content is reasonable and adds no unnecessary parameter detail.

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

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

The description uses a specific verb ('Get') with a clear resource ('email-alert settings') and enumerates exactly what data is returned: enabled state, cadence, fastest allowed cadence, and cadence options. This clearly differentiates it from the sibling update_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 clearly establishes that this tool retrieves alert settings, and the sibling name update_alert_settings provides an obvious contrast for mutation. It does not explicitly say 'use update_alert_settings to modify settings,' but the read-only retrieval context is unambiguous.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context by stating the response includes all keywords and their statuses. No side effects need disclosure, and the output schema covers return structure.

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

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

A single sentence that front-loads the action and target, with no filler or redundant phrases. Every part of the description 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 simple single-parameter read tool with an output schema and complete annotations, the description covers the key return content (keywords and statuses), and the input is fully specified in the schema. Nothing material is missing.

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

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

Schema coverage is 100%, and the websiteId parameter is already described as a UUID. The description only restates 'by ID' in natural language, adding no new meaning beyond what the schema already provides.

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

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

The description states a specific verb ('Get'), resource ('single monitored website'), identifier method ('by ID'), and return scope ('including all of its keywords and their statuses'). This clearly distinguishes it from list_websites (bulk listing) and update_website (mutation).

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 phrase 'single ... by ID' clearly implies this tool is for fetching one known resource, with list_websites as the natural alternative for multiple websites. However, it does not explicitly name the alternative or give an explicit when-not-to-use condition.

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. The description adds meaningful behavioral context beyond the annotations: the meaning of limit -1, the fact that adding/disabling are unlimited, and that only edits consume allowance. This is useful domain behavior not derivable from the schema or annotations.

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

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

The description is two sentences with no filler. The primary action and resource appear first, and the clarifying detail about limit -1 and unlimited operations is placed immediately after, making it easy for an agent to parse quickly.

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

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

The description is fully adequate for a zero-parameter read-only tool. It explains the key business rule (only edits count), the meaning of the unlimited sentinel, and the distinction from related keyword mutation tools. The presence of an output schema covers return value details, so no additional information is needed.

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

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

The tool has zero parameters and the schema covers 100% of the surface, so there is nothing for the description to add about parameter meaning. With no parameters, the baseline is 4, and the description appropriately focuses on the return semantics instead.

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

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

The description uses a specific verb and resource: 'Get the current monthly keyword-EDIT allowance and how much is used.' It also clarifies the semantics of limit -1 and explicitly distinguishes editing from adding/disabling keywords, which helps differentiate it from sibling tools like edit_keyword, add_keywords, and disable_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?

The description clearly implies when to use this tool: when needing to check the keyword-edit allowance before performing edits. It states that adding and disabling keywords are unlimited, so the tool is only relevant for edit operations. However, it does not explicitly name an alternative tool or spell out 'use this instead when...' so it stops short of a full when/when-not guide.

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 this as read-only and non-destructive. The description adds meaningful behavioral detail: REJECTED mentions are excluded by default, sub-30 relevance mentions are hidden, and includeLowRelevance overrides the hidden default. This goes beyond what annotations alone provide.

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

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

Three compact sentences with no filler. The core purpose is front-loaded, default behavior is stated clearly, and available filters are enumerated efficiently.

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

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

The description covers the core behavior, default filters, override behavior, and filter surface. Combined with the rich input schema, output schema, and read-only annotations, the agent has enough context. The slight ambiguity around includeLowRelevance and REJECTED exclusion keeps it from a perfect score.

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

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

Schema coverage is 100%, so the baseline is 3. The description does add default-behavior context, especially for includeLowRelevance, but the phrase 'set includeLowRelevance to see everything' is slightly misleading because that parameter only controls the <30 relevance filter, while REJECTED exclusion is a separate statuses concern.

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 a list operation, the resource ('mentions'), the account scope, and the specific sources included. It also adds a distinguishing detail (AI-scored relevance 0-100) that separates it from siblings like count_mentions or update_mention_status.

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 clear context for when the tool is useful: listing account-matched mentions across multiple platforms, with filtering and default exclusions. It doesn't explicitly name sibling alternatives or say when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description aligns with those. It adds useful behavioral context by stating that the response includes each website's keywords with value and status, which is beyond what the annotations convey.

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

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

The description is two sentences with no filler. The primary action and scope are front-loaded, followed by the return contents and usage guidance, so 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?

With no parameters, a read-only annotation, and an output schema present, the description covers everything an agent needs: what is listed, what fields are included, and how to use the result with sibling tools.

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

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

The tool has zero parameters, so there are no parameter semantics to clarify. The description compensates by explaining what the tool returns and why it is useful, which is the relevant semantic content for an agent.

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 ('List'), a concrete resource ('all monitored websites for this account'), and the included keyword details with statuses. It also clearly distinguishes this from siblings like get_website by indicating this is the starting point for obtaining IDs.

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 to start here and explains why: most other tools require website IDs and keyword IDs. This gives an agent clear guidance on when to invoke this tool in a workflow.

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 safety profile is known. The description adds value by stating 'without making any change' and explaining the billing calculation details (current vs target plan, prorated immediate charge), which go beyond the annotation metadata.

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

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

A single, front-loaded sentence contains all essential information: the action, the object, the key output details, and the non-mutating guarantee. No wasted words.

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

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

For a zero-parameter, read-only preview tool with an output schema present, the description covers everything an agent needs: what is being previewed, the key calculation dimensions, and the guarantee that no change is made. Nothing critical 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 and schema description coverage is 100%, so the description has no obligation to explain parameters. It still enriches understanding by describing what the preview computes.

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

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

The description uses a specific verb ('Preview'), identifies the exact resource ('billing impact of activating all currently pending keywords'), and clarifies scope ('current vs target plan, prorated immediate charge'). The phrase 'without making any change' clearly distinguishes it from the sibling activation tool.

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

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

The description implies when to use the tool — as a safe preview before committing to activation — but it does not explicitly name alternative tools or state when not to use it. Since a similar sibling (preview_keyword_billing) exists, the lack of explicit routing leaves some 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, so the safety profile is captured structurally. The description adds the useful behavioral detail that nothing is changed during the preview, reinforcing the annotations, but it does not disclose other behaviors such as cost calculation caveats or plan-tier assumptions beyond what the annotations and output schema already communicate.

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, front-loaded sentence that states the action, the object, the condition, and the safety guarantee without any filler. Every word contributes value.

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

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

For a simple preview tool with one well-documented parameter, explicit read-only annotations, and an output schema, the description fully covers the agent's needs. It explains what the tool does, what input it requires, and that it has no side effects, leaving no critical gap for correct invocation.

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

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

Schema description coverage is 100%, with the single parameter desiredKeywordCount already fully described as 'Total number of active keywords you want.' The tool description repeats this concept ('desired number of active keywords') but adds no new meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Preview') and resource ('plan and price required for a desired number of active keywords'), which clearly identifies the tool's function. The phrase 'without changing anything' reinforces that this is a read-only estimation tool and distinguishes it from sibling activation or keyword-management tools.

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

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

The description clearly implies the tool is for checking billing before committing to a keyword count, and the 'without changing anything' phrase signals a non-mutating preview. However, it does not explicitly name alternatives such as add_keywords or activate_pending_keywords, nor does it state when not to use it, so the guidance is mostly implied.

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

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

Annotations already signal a mutating/destructive operation. The description adds valuable behavioral detail: cadenceMinutes is restricted to specific values, clamped to the plan's fastest allowed interval, and omission falls back to the plan default. This goes beyond the schema and annotations without contradicting them.

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

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

Two tight sentences accomplish the job: the first states the tool's core purpose, and the second packs the essential constraints and default behavior. No filler or redundancy exists.

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 only two simple parameters, one required, and an output schema. The description, along with the schema and annotations, gives an agent everything needed to call it correctly: required enabled, optional cadence constraints, and mutating behavior.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra semantic value by clarifying the cadenceMinutes allowed set, the plan-based clamping behavior, and the default when omitted, which are not fully captured in the schema 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?

The description uses a specific verb-resource pairing: 'Enable/disable mention email alerts and set the cadence.' This clearly identifies the tool's action and distinguishes it from read-only siblings like get_alert_settings and from unrelated tools like delete_website.

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 clear parameter usage guidance, such as valid cadenceMinutes values, plan clamping, and the default behavior when omitted. However, it does not explicitly state when to choose this tool over get_alert_settings, so the usage context is implied rather than directly stated.

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

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

The description adds useful behavioral detail beyond the annotations: REJECTED hides the mention and excludes it from default lists, while NEW returns it to the inbox. This clarifies side effects of the status change. The annotations are consistent with the description, with no contradictions.

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

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

The description is compact and front-loaded, stating the operation in the first clause and then efficiently clarifying the three possible values. No redundant wording is present.

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 two-parameter mutation tool with an output schema, the description provides all necessary operational context. It explains the action and the practical consequences of each status choice, so an agent can invoke the tool correctly without additional information.

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 covers both parameters with 100% coverage, but the description enriches the status parameter by explaining what each enum value actually does. This goes beyond the schema's simple 'New status: NEW, APPROVED, or REJECTED' wording.

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, 'Set a mention's status,' and defines the resource being acted on. It also enumerates the meaning of each status value, making the tool's purpose precise and distinguishable from sibling tools like list_mentions or explain_mention.

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

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

The description provides clear context on when to use the tool: whenever a mention's status needs to be changed to APPROVED, REJECTED, or NEW. It does not explicitly name alternatives or exclusions, but the status semantics make the intended use obvious and distinct from read-only sibling tools.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation is known. The description adds useful context by explaining that the description field feeds AI relevance scoring and should be accurate, which is beyond the annotations. It does not elaborate on reversibility or side effects, but the annotated destructive hint covers the core safety signal.

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

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

Two sentences, with the core purpose front-loaded and a consequential caveat right after. Every sentence earns its place, and there is no redundant restatement of 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?

The tool is simple, the schema is complete, an output schema exists, and annotations carry the destructive hint. The description adequately covers what is updated and why the description matters. It could mention that existing values are overwritten, but 'New display name' and 'New description' in the schema already convey that.

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

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

Schema description coverage is 100%, so the schema already explains each parameter. The description adds value by explicitly connecting the 'description' parameter to AI relevance scoring and naming 'display name' and 'description' as the updatable fields, reinforcing their semantics 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?

Description clearly states the action ('Update a monitored website's display name or description') and identifies the resource and specific updatable fields. This distinguishes it from sibling tools like create_website, delete_website, get_website, and analyze_website without requiring schema inspection.

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

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

Description implies the use case: when you need to modify a monitored website's display name or description. It provides the context that the description affects AI relevance scoring, but it does not explicitly mention alternatives or when not to use this tool, so it falls short of a full routing guide.

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