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 past the annotations by disclosing quota cost (one AI generation), the caching exception (no charge if a precomputed description exists), the refund on failure, and specific error conditions (400 on exhausted quota or invalid URL, error on too little readable text). These are exactly the operational facts an agent cannot get from readOnlyHint/openWorldHint.

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

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

Front-loaded with purpose, then workflow, then quota and error behavior; every sentence carries information. Density is high but there is no filler, though the opening sentence stacks several clauses.

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-shape explanation is unnecessary, and the description still names the { description } field. Combined with annotations and 100% param coverage, an agent has everything needed to call it, interpret quota effects, and handle failures.

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 url and workspaceId are already documented in the schema. The description adds only the URL-validity failure mode and says nothing about workspaceId or cross-workspace id semantics, 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 and resource: read the public homepage and return an AI-written business description. It also carves out scope ('without creating or changing any website'), which separates it from create_website/update_website by name.

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

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

Explicit routing: use it to draft or preview text before create_website or update_website, then pass the result as their description. It states both the trigger and the follow-up action, 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 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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) by disclosing concrete failure modes: 400 on duplicate domain, 400 when plan slots are exhausted, revival of a domain deleted via delete_website, and the AI-generation quota cost of auto-drafting a description. It also explains the degraded path (description null, mentions unscored with reason string).

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 purpose, and nearly every clause carries operational information. It is dense and somewhat run-on in the middle, but there is little genuinely wasted 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 write tool with an output schema, this covers the remaining gaps an agent needs: prerequisite conditions (new domain, free slot), side effects (PENDING keywords, background AI suggestions), quota consumption, and the fallback state to check after the call.

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: url must be a domain new to the account, description is the scoring context every mention is measured against (and what happens when omitted), and keywords land in PENDING until activated. This supplements rather than repeats 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 and resource ('Add the user's own website to their RedReplier account') plus the downstream effect (finding public posts on Reddit, Hacker News, X, Bluesky, Facebook). It is clearly distinguishable from sibling mutations like update_website and 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 duplicate-returns-400 rule implicitly routes an agent to update_website for existing domains, and it explicitly names update_website/analyze_website for fixing a missing description and add_keywords/enable_keyword for activating PENDING keywords. It stops short of a crisp 'use this when / not when' statement, but the context is clear.

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

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

Annotations 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?

With destructiveHint=true already declared, the description goes well beyond annotations: it discloses the ACTIVE-vs-PENDING capacity outcome, that it never charges or upgrades, that an already-active keyword is returned unchanged (idempotency), that alerts are synchronized, and that no historical backfill occurs. This is exactly the side-effect context a mutation tool 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?

Five short sentences, purpose front-loaded first, then state outcomes, cost boundary, idempotency, and the sibling redirect. No sentence is 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?

An output schema exists, so return values need not be explained, and the description fully covers the state machine, cost implications, and non-backfill behavior an agent must know before calling. 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 description coverage is 100%, so keywordId and workspaceId are fully documented in the schema itself (including the cross-workspace id caveat). The description adds no parameter-level detail, which is the expected baseline when 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?

States a specific verb (Enable) and resource (an existing keyword within the current plan), and explicitly routes new-keyword creation to the sibling add_keywords. An agent can distinguish this from disable_keyword/add_keywords 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?

Names the alternative (add_keywords) and the condition selecting it, plus states the no-charge/no-upgrade constraint that bounds when this is appropriate. It does not explicitly cover the inverse case (when to prefer disable_keyword), so it stops just short of full when/when-not 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?

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 declare readOnly/openWorld=false/destructive=false, and the description reinforces this ('Reads mentions already saved in the account; it does not search or contact any network') and adds genuinely non-obvious behavior: two default filters that silently drop rows, the minScore/website-minimum stacking, and the privacy boundary that private Facebook groups are never read. It does not state rate limits or what happens on invalid pagination, but the substantive behavioral gaps 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?

A single dense paragraph that front-loads what is listed, then defaults, then return/pagination, then constraints and siblings — highly efficient for 13 parameters. Minor redundancy remains (the first sentence already lists content, and a later sentence re-describes text/URL/author handle to make the privacy point), so it falls just short of zero waste.

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

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

Given 13 optional parameters, an output schema, and safe-read annotations, the description covers everything an agent needs: what is returned, how to page, how defaults silently filter, time-field semantics, and which sibling to use instead. No material 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?

With 100% schema coverage the baseline is 3, but the description adds real meaning beyond the schema: from/to filter on ingestion time not publish time, keywords follow the values shown in list_websites, minScore stacks on the website minimum, and scoreBuckets LOW/VERY_LOW only surface when includeLowRelevance is true. It also supplies the limit/offset/total return contract that pagination depends on.

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 and an explicit scope ('mentions RedReplier saved for the user's keywords'), enumerates the sources covered, and distinguishes itself from the three closest siblings (count_mentions, explain_mention, update_mention_status). An agent can identify this tool without opening its 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 to count_mentions, explain_mention and update_mention_status, plus when-to-use sort values (RELEVANCE for best leads, RECENT for what is new) and the exact conditions for surfacing hidden rows (name statuses to see REJECTED; set includeLowRelevance to go below the website minimum). 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.

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds the data scope ('Reads the account's saved settings only'), which is useful, but says nothing about pagination, result limits, or ordering, and the returned-field detail is largely duplicated by the output schema. Adequate but not rich.

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

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

Three short sentences, front-loaded with what is returned, then the routing rule, then the chaining note. No filler and nothing buried.

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 annotations covering the read-only profile, a fully documented single parameter in the schema, and an output schema describing return shape, the description supplies everything else an agent needs: the resource, the sibling routing, and the ID-chaining relationship.

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

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

There is a single optional parameter (workspaceId) with 100% schema description coverage, so the schema already carries the semantics including the cross-workspace ID caveat. The description never mentions workspace scoping, so it adds nothing beyond the schema; 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 ('List the user's own websites saved in their RedReplier account') and enumerates the returned fields, including nested keywords with ID, text, and status. It also distinguishes itself from get_website, 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?

Names the alternative explicitly and the condition that selects it: 'Use get_website for one website when you have its ID.' It further explains the downstream chaining ('The website and keyword IDs are the inputs for the other tools'), which tells the agent when this call is the prerequisite step.

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?

Adds substantial behavior beyond the annotations: full reversibility between any statuses, the reviewedAt stamp/clear rule, the downstream effect on list_mentions/count_mentions, and mentionId provenance. Although destructiveHint=true, the description discloses the mutation is reversible and scoped, which meaningfully informs the agent.

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

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

Front-loads the core action, then layers status semantics, reversibility, and judgment guidance. Everything earns its place, though the semicolon-heavy single block is denser than ideal.

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 annotations covering the safety profile, a 100% schema coverage, and an output schema for the return value, the description fills the remaining behavioral gaps (reversibility, timestamp, downstream effects, guidance). Nothing needed 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 3 is the baseline, but the description adds real invocation value by stating where mentionId comes from (list_mentions) and restating the status enum semantics. workspaceId is left entirely to the schema, so it does not fully compensate, but it exceeds the 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 ('Set one mention's triage status') and then defines exactly what each status means, including the distinct effects of APPROVED, REJECTED, and NEW. An agent can distinguish this from siblings like explain_mention or list_mentions 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?

Gives explicit operating guidance: judge on content and relevanceScore, call explain_mention first when the score looks off, and never approve an unread mention. It also names the concrete side effect that REJECTED drops the mention from default list_mentions and count_mentions results, with the workaround to pass statuses.

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.