RedReplier

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

Annotations only declare readOnly=false, destructive=false, openWorld=true; the description adds substantial context beyond that: normalization (trim/lowercase/dedup), skip/re-propose rules, the pending-then-active lifecycle, no-charge within plan, entitlement overflow staying pending, and side effects (alert updates, queued public-network searches and ranking checks). This is unusually rich behavioral disclosure for a mutation 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?

Front-loaded with the core action, then flows through lifecycle and side effects; every sentence carries information. It is on the longer side but not padded, with only minor overlap between the description and the keywords schema field.

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?

Output schema exists, so return-shape explanation is optional; nonetheless the description notes it returns the whole website. Combined with the lifecycle, billing, and side-effect disclosure, an agent has everything needed to call this 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 schema already documents the trim/lowercase/dedup and 255-char limit for keywords plus the workspaceId guidance. The description restates normalization behavior rather than adding new parameter-level meaning, so the 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?

Opens with a specific verb+resource ('Add keywords to a monitored website') and explicitly routes the closely-related case to a named sibling ('Use edit_keyword to change existing text'). An agent can distinguish add_keyword from edit_keyword 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 clear conditions that determine the outcome (active values skipped, disabled may be re-proposed) and names edit_keyword as the alternative for changing existing text. It stops short of stating explicit when-not-to-use scenarios beyond that single sibling reference.

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?

Goes well beyond the annotations by disclosing the AI-quota cost, the refund-on-failure behavior, and specific error conditions (400 on exhausted quota or invalid URL, error on too-little readable text). The only minor gap is that it does not explain why readOnlyHint is false despite being non-mutating, though the quota consumption plus 'without creating or changing any website' largely covers that tension.

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-loads the core action, then usage, then cost/refund, then error semantics in a tight three-sentence block with no filler. 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?

Output schema exists so return values need no explanation, yet the description still names the returned field ({ description }). Quota, caching, failure refund, and error paths are all covered, leaving nothing an agent needs to call this 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%, so both url and workspaceId are already fully documented in the schema. The description only indirectly adds meaning (valid-URL requirement, domain-keyed caching) and adds no syntax or format detail beyond what the schema provides, so the baseline 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?

States a specific verb+resource ('Scrape a URL and return an AI-written business description') and immediately scopes it negatively ('without creating or changing any website'), which separates it from the create_website/update_website siblings. An agent can tell what this does and what it does not do without reading 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?

Explicitly names the when ('draft or preview the text before create_website or update_website') and the downstream step ('pass the result as their description'). It also names two alternatives by name, which is the highest form of routing guidance.

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

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

Annotations already declare readOnly, non-destructive, and closed-world behavior. The description adds important default-filtering behavior: REJECTED is excluded unless statuses includes it, low-score mentions are hidden unless includeLowRelevance is true, and sort/limit/offset are not accepted.

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 return shape, then defaults, then usage guidance. Every sentence contributes useful routing or filtering information, and there is no filler.

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

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

For a ten-parameter read tool with an output schema, this is complete. It explains the return shape, default exclusions, relevance filtering, sibling relationship, and the absence of pagination controls, leaving no material gotcha for an agent to discover.

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 all ten parameters are already documented in the schema. The description reinforces default semantics for statuses and includeLowRelevance and notes the absence of sort/limit/offset, but adds little parameter-level syntax beyond what the schema 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?

States a specific verb and resource: counting mentions. It immediately distinguishes itself from the sibling list_mentions by explaining that it returns only { total } and no rows, so an agent can tell the two apart 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?

Explicitly names when to use it (dashboards, sizing a triage batch, deciding whether paging list_mentions is worthwhile) and when to skip it (when you are already fetching rows via list_mentions). It routes the agent between alternatives with a clear 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?

Far exceeds the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), which only establish that this is a non-destructive write. The description discloses duplicate-400 behavior, revival of deleted domains, the quota cost of an omitted description, the null-description consequence (unscored mentions with a specific reason string), PENDING keyword promotion timing, and background AI keyword addition.

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 platform scope, and every sentence carries non-redundant information. It is a single dense block, though, and the keyword/quota/description rules would scan faster as separated clauses or bullets.

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?

An output schema exists, so return shapes need not be documented, yet the description still covers the 400 cases an agent must handle and the follow-up tools for repairing a null description. 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, and the description adds real meaning on top: it explains that omitting description triggers a URL scrape that consumes one AI generation, that scrape failure or exhausted quota yields a null description, and that keywords land in PENDING until promoted. This goes beyond the schema's terser parameter notes.

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 and resource ('Add a website to monitor') and immediately scopes it across named platforms (Reddit, Hacker News, X, Bluesky, Facebook). An agent can distinguish it from update_website, delete_website, and analyze_website 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?

Gives clear operational conditions: the domain must be new, a duplicate returns 400, and re-adding a deleted domain revives the record. It also routes the agent to update_website or analyze_website when the description ends up null. It does not frame when another sibling would be preferred as the primary action, but for a create tool that is inherent.

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 flag destructive/openWorld/non-readOnly, but the description adds substantial context beyond them: no undo or restore, the plan-slot cascade that can activate the oldest pending keyword and queue public-network searches and ranking checks, and the absence of a refund or subscription change. These are non-obvious side effects an agent must warn about before calling.

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 irreversible action, then siblings, then side effects, then confirmation and return/error behavior. Despite its length, every sentence carries distinct decision-relevant information with no filler.

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

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

For a destructive, open-world mutation, it covers irreversibility, cascading side effects, sibling alternatives, confirmation requirements, and error behavior (404 for unknown ID). An output schema exists, yet the description still notes the return shape, so nothing needed to call it safely 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%, so both keywordId and workspaceId are already documented in the schema, establishing the baseline of 3. The description adds only the workflow hint to name the keyword rather than just the ID, which is marginal 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?

States a specific verb+resource ('Permanently delete one keyword') with explicit scope ('in any status, together with every mention it produced'). It immediately names the sibling tools it is not (disable_keyword, edit_keyword, delete_website) and the conditions that separate them, so an agent can disambiguate 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?

Gives explicit when-to-use and when-not routing: disable_keyword to pause and keep mentions, edit_keyword for a SUSPENDED value, delete_website for a whole site. It also adds a precondition ('Confirm with the user first and name the keyword, not just the ID'), 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?

Goes well beyond the annotations (destructiveHint=true, openWorldHint=true) by disclosing cascade effects: keywords leave list_websites, active keywords free plan slots, pending keywords may auto-activate, and searches/ranking checks get queued. It also discloses irreversibility ('no restore tool') plus the recovery workaround (create_website with the same URL), and the return/error contract (404 if ID unknown).

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 its soft-delete nature, then layered as consequences, alternatives, and confirmation. Every sentence carries operational weight — cascade effects, irreversibility, and routing are all non-redundant.

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 destructive, open-world mutation the description covers impact, reversibility, side effects on sibling entities, alternatives, and the error contract. With the return payload ({ deleted: true }) and recovery path both noted, nothing an agent needs to call this safely 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, and the description only marginally extends it. However it does add account-scoping meaning ('404 if the ID is unknown to this account') and advisory semantics for websiteId ('name the domain, not just the ID'), which help the agent use the parameter correctly rather than just pass it through.

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 and resource ('Stop monitoring a website (soft delete)') and immediately clarifies the soft-delete semantics. It distinguishes itself from delete_keyword and disable_keyword by scoping the action to the whole site, so an agent can route correctly 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-not-to-use ('use this only when the whole site should go') and names the two alternatives with their distinct conditions (disable_keyword to pause, delete_keyword to erase). It also adds a procedural prerequisite ('Confirm with the user first and name the domain').

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 give the coarse destructive/openWorld/readOnly profile; the description adds real behavioral context beyond them: mentions are kept, alert synchronization occurs, a plan slot is freed, the oldest pending keyword may auto-activate and queue public-network searches and ranking checks, and no billing change occurs. That is a genuine disclosure of side effects and cascade behavior. It does not contradict destructiveHint=true (state is mutated), though the retention of mentions nuances 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?

Front-loads the core action and consequence before the sibling routing, and every sentence carries information. It is on the longer side, but the density is justified by the cascade and billing caveats; little could be cut without losing useful signal.

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?

An output schema exists, so return values need not be explained, and the description still covers alternatives, idempotency, side effects, and the billing boundary. Nothing an agent needs to invoke this mutation safely appears to be 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%, so keywordId and workspaceId are already fully documented in the input schema, including the workspace-scoping advice. The description adds no format, syntax, or constraint detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('Set one keyword to DISABLED and stop matching new mentions') and immediately differentiates itself from the two nearest siblings by naming enable_keyword and delete_keyword with their distinct semantics. An agent can distinguish disable from enable/delete 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?

Gives explicit when-to-use routing: use enable_keyword to resume monitoring, delete_keyword to permanently erase, and this tool to stop matching while retaining history. It also documents the idempotent case ('an already disabled keyword is returned unchanged'), which tells the agent a redundant call is harmless.

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 flag destructive/openWorld; the description goes well beyond them by disclosing re-grading, replacement of matching rules, plan-space-dependent activation, queued public-network searches and ranking checks, alert synchronization, case-only no-ops, and duplicate failure. For a destructive mutation, this is exactly the side-effect detail an agent needs.

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

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

The core purpose is front-loaded and every sentence carries behavioral payload; no filler. It is dense to the point of being a run-on chain of clauses, but nothing 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?

With an output schema present, return values need not be described, and the annotations plus this rich behavioral text cover side effects, activation rules, and error conditions. Nothing an agent needs to invoke 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 semantics the schema lacks: case-only edits are a no-op (a nuance beyond 'trimmed and lowercased') and that old text/matching rules are overwritten. It still says nothing extra about workspaceId semantics, so not a 5.

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

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

The first sentence gives a specific verb and resource plus the key invariant ('Replace a keyword's text while keeping its ID'), which cleanly separates it from add_keywords, delete_keyword, and enable/disable_keyword. An agent can identify the operation without opening 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?

Usage is implied rather than stated: the description makes clear this changes text (not status or existence), but it never explicitly says when to reach for this vs. enable_keyword or delete_keyword. There are no named alternatives or exclusion conditions.

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 rich behavioral context beyond annotations: state transitions (ACTIVE if capacity, else PENDING), no billing side effects, no historical backfill, and monitoring alert synchronization. Annotations already declare a non-read-only, non-destructive operation; the description elaborates on the exact mutation semantics.

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

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

The description is front-loaded with the core action, followed by tightly packed operational details. Every sentence earns its place—no redundancy or 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?

Given the mutation nature, existing annotations, full parameter schema, and an output schema, the description covers all relevant behavioral concerns an agent needs (state outcomes, idempotency, no backfill, billing safety). 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?

Schema description coverage is 100% and fully documents both parameters (keywordId, workspaceId), including workspace scoping details. The description adds no additional parameter meaning, so the baseline of 3 for high schema coverage 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?

States a specific verb ('Enable') and resource ('existing keyword') with scope ('within the current plan'), and explicitly distinguishes itself from the sibling add_keywords for new keywords. An agent can identify the tool's purpose immediately.

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 add_keywords as the alternative for creating a new keyword, and clarifies idempotency ('already active keyword is returned unchanged'). It does not explicitly compare to disable_keyword, but the implied usage is clear from the verb.

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?

Despite readOnlyHint=false, the description explains the write-on-first-call/stored/cached-read behavior that justifies that annotation, plus a precondition (website must have a description or the mention returns unchanged) and the null-not-404 edge case. These are exactly the traits annotations cannot 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?

Three dense sentences, front-loaded with what is returned and the caching behavior, then usage rules. No filler.

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

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

For a generating-read tool with an output schema, the description still supplies the non-obvious essentials: laziness/caching, the description precondition, latency warning, and null return semantics. Nothing an agent needs to invoke 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% and both parameters (mentionId, workspaceId) are already fully documented, so the description only implies 'for one mention'. Baseline 3 is appropriate given 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?

Specific verb+resource plus the exact fields returned (relevanceReason, tags, aiReplySuggestion), which lets an agent distinguish it from list_mentions and other mention siblings without opening the schema. It also states the scope ('for one 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?

Explicit when-to-use ('when a score looks wrong or before update_mention_status on a borderline lead') and when-not ('not across every row of list_mentions, since generation is slow'), naming two siblings by name.

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 'Read-only.' It adds genuine behavioral context beyond the annotations: the plan-floor clamping rule (cadenceMinutes never reported below the floor even after a downgrade) and the fact that digests are dispatched by the platform rather than this tool. It does not cover auth/permission needs, but for a read-only getter that is a minor gap.

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

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

Front-loaded with the purpose and the returned fields, and every sentence carries information (field meanings, the floor rule, usage timing, read-only note). It is somewhat dense with parenthetical enumerations, but nothing 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?

An output schema exists, yet the description still explains the semantics of the returned fields and the clamping behavior an agent must account for. Combined with a fully documented parameter and covering annotations, nothing needed to call or interpret this tool 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 single workspaceId parameter is fully documented in the schema, including default behavior and cross-workspace id scoping. The description adds no parameter-level detail beyond that, so the baseline 3 is appropriate.

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

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

States a specific verb+resource (get the account's email-alert settings) and enumerates the exact fields returned: enabled, cadenceMinutes, minIntervalMinutes, availableCadences. Clearly distinct from the sibling update_alert_settings, which it names.

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 prescribes when to call it: before update_alert_settings to pick a value from availableCadences, and after it to confirm what applied. Both the before and after conditions are stated, 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds genuinely useful behavior: the four possible status values and the error semantics (404 for missing/other-account websites, 400 for a non-UUID id), which an agent cannot infer from annotations or schema.

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 dense sentences, each earning its place: what it returns, when to use it versus the sibling, and failure modes. The primary purpose and return payload are front-loaded.

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

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

An output schema exists, so return value structure need not be explained, and the description still covers routing, ID provenance, and error behavior. Nothing needed to call this tool 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 the provenance of websiteId (list_websites or create_website) and reinforces that workspaceId matters. It adds modest value over the schema's own parameter descriptions rather than just restating them.

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 (get) and resource (one monitored website) scoped by ID, and explicitly lists what is returned (full keyword list and statuses with enum values). It names list_websites as the sibling it is not, so an agent can distinguish it 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?

Explicitly says to use it to re-check keyword statuses after add_keywords or enable_keyword, and to use list_websites instead when the ID is unknown or all sites are wanted. It also states where websiteId comes from, leaving no routing 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 establish readOnlyHint=true, destructiveHint=false, and openWorldHint=false. The description adds valuable behavioral context beyond annotations: only edit_keyword ever counted toward the allowance, add_keywords/disable_keyword/enable_keyword never did, and this tool does not change capacity, sell a plan, or initiate payment.

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

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

The description is front-loaded with the core purpose and return semantics, then adds only high-value disambiguation about counting rules, current-plan behavior, and side effects. 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?

Given one optional parameter, full schema coverage, output schema presence, and the tool's reporting role, the description is complete. It explains the response fields, the -1 unlimited convention, usage context, and explicitly rules out unrelated side effects.

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 100% description coverage and documents workspaceId thoroughly, including default behavior and workspace-id scoping. The description does not mention the parameter or add meaning beyond the schema, so the baseline 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?

States a specific verb and resource ('Get the monthly keyword-edit allowance') and describes the returned fields directly. It also distinguishes this reporting tool from edit_keyword and the other keyword mutation siblings by explaining which operations count toward the allowance.

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

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

Explicitly says there is no need to check it before edit_keyword because every current plan reports unlimited, and clarifies it remains for clients that budget edits. This gives both when-to-use and when-not-to-use guidance relative to a named sibling.

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

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

Annotations already mark readOnly, non-destructive, non-open-world; the description adds operational behavior: one entry per workspace with role/permissions/default/current, fallback to the current workspace when workspaceId is omitted, and API-key single-workspace scope. It also states 'Takes no arguments'.

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 purpose followed by return shape, usage, fallback, and API-key caveat. Mostly earns its place, though the return-field enumeration is partially redundant with the existing output schema.

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 zero-argument read tool: usage routing, workspaceId implications, API-key scope, and return structure are all covered. Output schema handles return details, and annotations cover safety.

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 parameters, so the schema baseline is 4. The description correctly confirms no arguments and does not need to add parameter details because none exist.

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 'List' and resource 'workspaces', with scope 'this sign-in can act in, across every organization the user belongs to'. It distinguishes from sibling list tools such as list_websites by focusing on workspace/organization context.

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

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

Explicitly says when to call: when the user names a workspace, client or organization, or when expected data is missing. It also routes the agent to pass the matching id as workspaceId to other tools and explains the fallback when workspaceId is absent.

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 mark this destructive (readOnlyHint false, destructiveHint true), and the description justifies why by disclosing the full-replace semantics and the reset-to-floor behavior on omission. It also reveals the plan-floor silent clamping and the precise 400 error string, which are not derivable from any structured field.

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-loads the action, then the hard requirements, then the failure modes, then the sibling routing. Every clause carries operational payload: validation set, error text, clamping, reset-on-omit warning, and the pre/post verification pattern.

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?

An output schema exists, yet the description still closes the loop with 'Returns the resolved settings,' which correctly signals that the applied cadence may differ from the requested one. With annotations, schema, and output schema all present, nothing needed to invoke 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 baseline is 3; the description still adds value by listing the allowed cadence values (the schema has no enum entry), quoting the 400 error, and describing silent clamping to the plan floor. It stops short of restating workspaceId behavior, which the schema already covers thoroughly.

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 (turn on/off, set cadence) and resource (mention email alert settings), and explicitly names the sibling get_alert_settings as the complementary read tool. An agent can distinguish it from update_website or update_mention_status 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?

Explicit routing: use get_alert_settings for availableCadences before and to confirm after; pass the current cadenceMinutes when only toggling enabled. The critical trap (both settings are replaced on every call) is stated as a warning rather than left 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?

Annotations only declare readOnlyHint=false, destructiveHint=false, openWorldHint=false; the description adds substantive behavior: full reversibility between any statuses, reviewedAt stamped when leaving NEW and cleared on NEW, and REJECTED being hidden from default results. It also states the return value, which goes beyond the safety hints.

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, then dense but purposeful clauses covering statuses, reversibility, and judgment guidance. Every sentence carries information, though the middle section is packed and could be marginally tighter.

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 status-mutation tool with an output schema already present, the description covers the mutation semantics, reversibility, side effects on other tools' default output, and prerequisites for safe use. Nothing material 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?

Schema description coverage is 100%, so the baseline is 3, and the description adds meaning on top: it names list_mentions as the source of mentionId and restates the functional consequence of each status value (hidden from default lists, back to inbox). It does not add much about workspaceId, which the schema already documents well.

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

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

Starts with a specific verb+resource ('Set one mention's triage status') and immediately enumerates the three status values with their meaning, so the agent knows exactly what the tool does. It is clearly distinct from sibling tools like explain_mention or list_mentions, which are referenced only as supporting 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?

Gives explicit routing guidance: call explain_mention first when relevanceScore looks off, never approve a mention you have not read, and mentionId comes from list_mentions. It also explains how to see REJECTED mentions again (pass statuses to list_mentions/count_mentions), covering the when-not path.

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 flag destructiveHint=true and readOnlyHint=false; the description goes well beyond by disclosing partial-update semantics, that an empty description clears the field, and that existing scored mentions are NOT rescored. That last point is a non-obvious side effect an agent must know. It stops short of covering permissions or failure modes, so 4 rather than 5.

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, then routing and semantics, with every sentence carrying usable information. The closing sentence about the return value is mildly redundant given an output schema exists, but the overall structure is tight and purposeful.

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 100% schema coverage, an output schema, and annotations present, the description supplies the remaining pieces an agent needs: mutable field set, partial-update behavior, side effects on scoring, and sibling routing. No meaningful gap remains.

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 adds real meaning beyond the schema: it explains what the description field is for (the scoring context for new mentions), how an empty string behaves, and that name/description are the only mutable fields. That lifts it above the schema-only baseline.

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

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

States a specific verb and resource ('Update a monitored website's display name and/or description') and immediately bounds the scope by declaring what cannot be changed (URL and keywords). An agent can distinguish it from edit_keyword/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?

Gives explicit when-to-use guidance (use analyze_website to draft a description first), explicit alternatives for the excluded operations (add_keywords, edit_keyword, disable_keyword), and the merge semantics for omitted fields. Nothing is left to inference.

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