CrunchJunkie

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false), the description discloses the two-step write flow: 'Requires MCP write actions; without confirm:true it returns a preview.' It also discloses the visibility default ('internal, team-only' unless showInReports:true). These are behavioral traits not captured by the annotations.

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

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

Front-loaded with the core purpose, then backdating guidance, then visibility default, then the confirm requirement — each sentence earns its place with no filler. Dense but efficient.

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

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

For a mutation tool with no output schema, the description covers what gets created, the preview/confirm workflow, the visibility behavior, and the write-action requirement. Nothing essential for calling 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 workflow-level meaning: it frames confirm/previewToken as a sequence (preview then apply) and reinforces the showInReports default semantics. It adds value beyond the schema without fully redefining parameter syntax.

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

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

States a specific verb ('Add') plus resource ('manual timeline annotation') scoped to a client's AI-visibility project, and elaborates with a concrete example ('site relaunch', 'TV campaign started') so the agent knows exactly what artifact this creates. It is clearly distinct from sibling add_* tools (add_market, add_widget, add_tracking_prompt).

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

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

The description gives clear usage context — use it to pin explanations onto charts so metric movements are explained, and it says to backdate to the day the event happened. It does not name any alternative tool or state when NOT to use it, so it falls short of the explicit when/when-not/alternatives bar.

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 write/non-destructive/non-open-world; the description adds far more: preview-only without confirm:true, requires MCP write actions, previewToken replay semantics, scan-cost computation (prompts × runs × engines, premium 3×), first-scan timing, run_scan caveat when a schedule exists, and that it writes an internal timeline note. No contradiction with destructiveHint=false, since the operation is additive.

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?

Core purpose is front-loaded, and nearly every clause carries needed information. However, it is delivered as one very long run-on sentence dense with em-dashes and semicolons, which hurts scanability; the refusal list and preview mechanics would be easier to consume as discrete sentences.

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?

Despite no output schema, the description covers the write lifecycle, preview/confirm flow, refusal cases, cost/timing of the first scan, and downstream relationships to other tools. An agent has everything needed to invoke this correctly, including the two-step preview-then-confirm pattern.

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 already 100%, but the description adds real meaning beyond it: prompts are 'reviewed by the user' texts or omitted to start empty, competitors default to the project list (and then track later project changes) versus a market-specific list used only for this market's share of voice, and confirm/previewToken are tied to the preview workflow.

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 market to a client's AI-visibility project') and immediately defines what a market is (country+language, own prompts/competitors, answers as seen locally). It also distinguishes itself from siblings by naming add_tracking_prompt, translate_prompts, and set_rank_schedule as adjacent-but-different operations.

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: pass prompts from translate_prompts, or none and add later via add_tracking_prompt; competitors default vs own list; engines/schedule come from the project and set_rank_schedule does not apply. It also enumerates precise refusal conditions (own market, duplicate market, language-alone vs country conflict, Peec import, trial prompt limits).

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

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

Beyond the annotations (which only say this is a non-read-only, non-destructive write), the description discloses idempotency (already-tracked keywords left as-is), input validation refusals (search operators rejected), the billing model (weekly runs on the workspace's DataForSEO account or budget-charged CrunchJunkie account, every keyword/engine costs), the write-action requirement, and the preview/confirm flow with cost preview.

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

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

Dense but front-loaded: the core action and scope come first, followed by defaults, refusal rules, cost model, and the confirm requirement. Most sentences earn their place, though the cost/billing sentence is long and packs 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?

For a 9-parameter, nested-object write tool with no output schema, the description covers the essentials an agent needs: defaults, idempotency, refusals, prerequisite lookup tool, cost implications, and the two-step preview/confirm invocation. Nothing critical to calling 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 already 89%, so the baseline is 3, but the description adds real meaning: it explains the tracks default and that each engine/surface adds cost, and the confirm/previewToken contract (preview without confirm:true). It still leaves some nested details (e.g. targetUrl nuances) to 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 ('Start tracking keywords for a client') plus the scoping dimensions (one place and language). 'Start tracking' clearly distinguishes it from update_rank_keywords and remove_rank_keywords among the siblings.

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 concrete operating context: defaults (Google desktop+mobile, top 100), that tracks switch on Bing/local lists, that existing keywords are skipped and operator keywords refused, and that location comes from find_rank_location. It does not explicitly route the agent to update_rank_keywords for modifying existing tracking, so it stops 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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false) by disclosing sanitization behavior (scripts, event handlers, unsafe links, frames and non-text-align inline styles are stripped), a 50,000-character cap, determinism ('the text goes in exactly as given'), default placement, and the preview/confirm auth flow. These are exactly the side-effect and constraint details an agent needs before a write.

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 action is front-loaded and every segment carries information, but the middle is one dense run-on paragraph mixing formatting vocabulary with constraints, which is harder to scan than it needs to be. It is sized appropriately for a 9-parameter tool, just not ideally structured.

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, no output schema, and annotations present, the remaining burden is behavioral context — sanitization, character limit, placement default, styling system, and the preview-then-confirm requirement — and the description supplies all of it. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it documents the permitted styling vocabulary (data-tone, data-mark, data-size, data-callout, hr) that the bare 'text: as HTML or plain text' field does not, and reinforces that position defaults to end. It does not, however, elaborate on anchorId/width semantics beyond what the schema states.

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

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

Opens with a specific verb+resource ('Add a TEXT widget — a free-text block you write yourself — to a report') and immediately names the boundaries: it is text, not a data widget, and edit_widget handles existing blocks. An agent can distinguish it from add_widget and edit_widget 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 routes to alternatives ('To change an existing text block call edit_widget with text; for a data widget (table, chart, KPI) call add_widget') and states the required workflow ('Requires MCP write actions; preview first, then confirm'). When-to-use, when-not, and alternatives are all present.

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

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

Annotations already declare this is a non-read-only, non-destructive write (readOnlyHint=false, destructiveHint=false). The description adds real value beyond that: the two-step preview-then-confirm workflow, the MCP write-action requirement, and the per-client prompt cap. The return value of a successful apply is not described, keeping it from a 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?

Three front-loaded sentences: purpose, constraint, then mechanics. The example earns its place by clarifying what a tracking prompt is. Slightly dense but 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 mutation tool with full schema coverage and annotations covering the safety profile, the description supplies the missing operational context (write-action requirement, cap, preview/confirm loop). With no output schema, it need not explain returns, though a word on the applied-success case would fully close the loop.

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

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

Schema description coverage is 100%, so the schema already carries full parameter documentation (including market, category filing rules, previewToken lifecycle). The description reinforces the confirm/preview selection but adds no syntax or meaning beyond what the schema states. 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 (add) and resource (AI-visibility tracking prompt), then defines the resource for the unfamiliar reader ("a query to monitor across AI engines") and grounds it with a concrete example. An agent can distinguish this from siblings like update_tracking_prompt, suggest_prompts, and add_market 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?

Clearly explains the preview-vs-apply branch ("without confirm:true it returns a preview") and the plan cap constraint, which tells the agent when the call can succeed. It stops short of naming alternative sibling tools (e.g. suggest_prompts for generating prompts), so the alternative-routing guidance is implicit rather than explicit.

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

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

With annotations only declaring readOnlyHint=false and destructiveHint=false, the description adds substantial context: it requires MCP write actions, returns a preview without confirm:true, describes the single-use 15-minute previewToken, discloses aiCost billing responsibility, and states fallback behavior when data isn't connected. This is rich disclosure well beyond the annotations.

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

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

Front-loaded with the core action and example, then structured with a PLACEMENT: marker and trailing fallback/alternative notes. It is dense and long, with some repetition of placement logic that also lives in the schema, but nearly every clause carries invocation-relevant 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?

For a complex 6-parameter mutation tool with no output schema, it covers interpretation, placement, preview/token flow, billing, and error/fallback behavior. The only minor gap is that it doesn't describe the shape of a successful (non-preview) result, e.g. the created widget id.

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 meaningfully extends the schema: granularity keywords (daily/weekly/monthly, incl. German) set chart time scale, a period is never read as one granularity, and placement/anchor semantics are elaborated. It adds genuine semantic detail over the parameter docs.

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

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

States a specific verb (add) and resource (DATA widget: table, chart, KPI) to a report, and explicitly distinguishes itself from the sibling add_text_widget for free-text blocks. An agent can tell it apart from related tools 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 alongside the add_text_widget alternative, explains the confirm:true / preview split, the placement defaults and overrides, and the blended-channel precondition (two or more paid ad accounts). Routing conditions and prerequisites are stated, not inferred.

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 auth requirement (MCP write actions), the preview/confirm token flow, and the plan client-cap constraint. These are exactly the behavioral traits an agent needs before invoking a write 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-loads the core verb and the default AI-visibility behavior, then adds constraints and the preview rule. The first sentence is dense with a long parameter enumeration, but there is no filler and each sentence carries distinct 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?

For a 20-parameter write tool with nested objects and no output schema, the description covers purpose, sequencing, auth, plan limits, and the preview confirmation mechanics. Nothing essential 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 schema already documents all 20 parameters in detail. The description enumerates the major ones (name, product type, profile, competitors, market, language, engines, passes) but adds no format or semantics beyond what the schema already provides, 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 (create) and resource (client / brand / domain) plus the default side effect of also creating the AI-visibility project. It distinguishes itself from the prompt-management siblings and is unambiguous 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?

Gives clear workflow context: prompts come afterwards via add_tracking_prompt, the plan's client cap applies, and the confirm:true vs preview behavior. It stops short of naming any alternative for creation (none exists), but the operational guidance is strong.

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

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

The description adds substantial context beyond the annotations: where the AI spend lands (workspace key vs Managed AI), that it is exempt from the scan allowance, the daily quota, the preview-until-confirm:true flow, and the no-gap short-circuit. The safety profile (openWorldHint, non-destructive) is already covered by annotations, and the description adds the third-party-data caution. Rich disclosure overall, though cost visibility is qualitative only (no magnitude of spend).

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 evidence sources, cost, preconditions, and return behavior in a sensible order. However, it is one sprawling em-dash-chained sentence; a couple of the parenthetical asides (proof/source caveat, refresh-or-new restated twice) could be tightened without losing meaning.

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 an 8-parameter, money-spending, open-world generation tool with no output schema, the description covers what it reads, what it writes, what it costs, what gates it, what it returns (preview vs. brief), and what it refuses to do. Nothing an agent needs before invoking it 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 schema already explains all 8 parameters including search, previewToken, and confirm. The description reinforces the preview→confirm contract and the refresh-or-new framing but adds no syntax or format detail beyond the schema, 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: 'Generate an evidence-grounded content brief for one tracked prompt,' and immediately scopes it ('the same brief as Content brief on the Prompts tab') and names its read-only sibling get_content_brief. An agent can distinguish this from get_content_brief and get_content_gaps 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 routes the alternative case: 'Read saved briefs for free with get_content_brief,' and states the preconditions to run at all (write actions AND 'Allow actions that spend AI', 20 assistant-started scans/briefs/refreshes per day). It also tells the agent the tool bails out when there's no real gap, which shapes when a call is worth making.

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: it discloses the confirm:true gating, that omitting confirm returns a preview and creates nothing, the workspace write-action requirement, and (via schema) the once/15-minute previewToken constraint. This is exactly the mutation-safety context the readOnlyHint=false annotation alone does not 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?

Front-loads the core purpose and flows logically into templates, refinement, and the confirm flow. The parenthetical enumeration of the "All channels" contents (totals, leads, cost per lead, spend, table) is more verbose than an agent strictly needs.

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 8 params and no output schema, the description covers the create flow, prerequisites, and preview/confirm behavior well. The only gap is that it doesn't describe what the preview actually returns, which matters slightly since there is no output schema to fall back on.

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 to the template/templates parameters by explaining the "All channels" blended section and its contents and the multi-source ordering, which the schema only hints at. It stops short of clarifying previewToken semantics beyond the schema.

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

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

Opens with a specific verb+resource ("Create a new report for a client") that is immediately distinguishable from siblings like get_report, schedule_report, update_report_settings, and create_share_link. The template pre-fill behavior and follow-up tools (add_widget/edit_widget) further pin down its exact role.

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 context and prerequisites (MCP write actions must be enabled; the "All channels" blend requires at least two paid ad accounts) and routes the agent to add_widget/edit_widget for refinement. It does not, however, explicitly state when to prefer this over alternatives like schedule_report.

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, readOnlyHint=false): it discloses that revoke permanently kills the URL and that a later create yields a new one, that an active e-mail schedule auto-regenerates a link, that anyone with the link sees all widgets/live numbers/AI summaries, that passwords are stored hashed and never returned, that Deleted reports cannot be shared, and that write actions require confirm:true or only a preview is returned.

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 semantics, then settings, then security/return behavior in a logical order with no filler sentences. It is dense and long, but nearly every clause carries actionable information; a slight trim would still be possible.

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

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

With no output schema, the description compensates by stating the return value ('Returns the share URL, on the workspace's verified custom domain when there is one') and by covering permissions, side effects, and the preview/confirm protocol. Nothing essential 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 coverage is 100%, so baseline is 3. The description nonetheless adds effect-level meaning: enabled=false keeps the link but shows 'not available', password null removes it and is stored hashed, allowDateChange exposes data beyond the report's own range, and confirm/previewToken govern the preview-then-apply flow.

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 set (create/update/revoke) on a specific resource (a report's share link, anchored to the Share panel). It explicitly distinguishes itself from siblings: 'It does not e-mail the link (send_report does) and does not change the report.'

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?

Explains exactly what each of the three actions does and when each applies (create vs update vs revoke), names the alternative tool for e-mailing, and states the confirm/preview precondition. An agent knows both when and when-not to call it.

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

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

Far exceeds the annotations: it discloses that approving spends no AI and starts no scan, that a share link becomes viewable by anyone holding it, that dismiss moves a drafted report to Deleted, and that the tool refuses to act without an explicit decision and confirm:true. It also explains the preview-then-confirm handshake required before mutation.

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

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

Front-loaded with purpose and decision semantics, then delivery outcomes, then constraints. It is long, but nearly every clause carries distinct operational information; the share-link and manual-task details could be tightened slightly.

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

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

For a mutation tool with no output schema, the description covers side effects, permission requirements, the confirmation protocol, and what it refuses to do. An agent has everything needed to call it correctly and safely.

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 a 3, but the description adds workflow semantics the schema does not: calling without confirm yields a preview of who receives what, and confirm:true must be paired with the token from that same preview. The two-step contract is explained in prose rather than left to the field descriptions.

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

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

States a specific verb pair (approve/dismiss) plus the exact resource and scope ('ONE item of the Approvals queue'), and anchors it to the UI affordance the user knows. It is immediately distinguishable from the sibling list_pending_approvals, which it explicitly names as the id source.

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 per-case outcomes (what approve delivers for an action plan, content brief, report draft, manual task; what dismiss does), states exclusions ('does not edit a draft, assign a task or change an automation'), and names the prerequisite 'Requires MCP write actions.' Nothing about when to call it 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?

Far exceeds the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false): it discloses catalog validation and refusal semantics, deterministic receipts comparing before/after, undo payloads for moves, previewToken validity (15 minutes, single use, bound to exact args), AI cost attribution via aiCost, and a detailed HTML sanitization allowlist (scripts, handlers, javascript: links, iframes removed). These are the operational facts an agent needs and they are not in the structured fields.

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

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

Purpose is front-loaded in the first clause and the document is segmented by mode (GRANULARITY, MOVE ONE WIDGET, SECTION ops, TEXT widgets). It is long, but the length tracks real tool complexity (7 params, several distinct modes) and nearly every sentence carries a decision-relevant rule; some of the sanitization detail could be trimmed without loss.

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

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

With no output schema, the description fully covers the return contract: a deterministic field-by-field receipt, the previous configuration for restore/undo, from/to positions for moves, and the aiCost field. It also covers prerequisites (write actions, confirm + previewToken) and refusal behavior, leaving no material gap for correct invocation.

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

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

Schema coverage is 100%, so the per-parameter text already carries basic meaning; the description adds genuine extra semantics: widgetId pins vs otherwise inferred, move{position,anchorId} bypasses AI and also previews from/to, text replaces the body verbatim with no AI, and instruction is ignored when move/text is supplied. It does not add syntax detail the schema lacks, so it sits just above the baseline rather than at the top.

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 ("Edit an existing report widget") and immediately illustrates with concrete plain-language examples ("make the sessions chart weekly", "turn the donut into a bar chart"). It clearly delineates the tool's multiple modes (edit, move, section ops, text-widget replacement) and explicitly contrasts itself with add_widget and remove_widget, so an agent can place it against its siblings without opening schemas.

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

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

It is unusually explicit about when to use which mode: pass widgetId to pin the target vs let AI identify it, use widgetId+move for deterministic no-AI moves, note that TEXT widgets are not edited by instruction, and that removal is achievable via instruction. It also states the alternative path for text (write the body yourself and pass `text`) and the precondition ("Requires MCP write actions; without confirm:true it returns a preview").

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, non-destructive and non-open-world, so safety is covered. The description adds genuine behavioral value by disclosing that items in Deleted/trash return with deleted: true in metadata, a return-value trait not present in the annotations.

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

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

Two tight sentences, both front-loaded with the essential action and the id contract first, then the trash edge case. No filler or redundancy.

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

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

With no output schema, the description carries some return-value burden and does cover the notable deleted: true edge case for trashed reports. It doesn't describe the general item shape returned, but for a low-complexity single-param lookup the coverage is nearly complete.

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

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

Schema description coverage is 100% and the single id parameter is fully documented with matching examples in the schema itself. The description's id-format examples duplicate rather than extend 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 (fetch) and resource (a single item), and pins down the expected input shape with concrete id formats (report:<id> or client:<id>). This partly distinguishes it from the many get_* siblings by tying it to ids produced by search, though it doesn't explicitly contrast with get_report or get_content_brief.

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?

"by the id returned from search" implies a prerequisite workflow (search first, then fetch), which is useful implied guidance. However, it never names alternatives or states when to prefer fetch over a dedicated sibling like get_report, leaving selection 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 a safe read operation, but the description adds real behavioral context beyond them: the corpus is incomplete (not every postcode), coordinates are a normalisation escape hatch, and a returned bingExact=false signals Bing cannot be targeted at that place. It does not describe pagination or the full response shape.

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

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

Three sentences, front-loaded with the core purpose, and each clause carries information (fallback, vendor source, bingExact caveat). Slightly dense with parentheticals but 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?

With no output schema, the description usefully names key return fields (places, locationCode, bingExact) and the fallback behaviour, which is enough for a 2-parameter lookup. It stops short of describing the response envelope or multiplicity of matches.

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 meaning the schema does not: that 'lat,lng' input is normalised and that this route enables tracking places missing from the list. Country scoping is only implied.

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 ('find the place a keyword should be searched from') and pins the exact artifact returned: DataForSEO places carrying the locationCode that add_rank_keywords needs. That linkage makes it unmistakable against siblings like search or add_rank_keywords.

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

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

Explicitly frames this as the prerequisite step for add_rank_keywords and gives a concrete fallback path (coordinates as 'lat,lng') when a postcode is absent from the list. No explicit when-not-to-use statement, so it falls just short of 5.

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

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

Annotations only cover the safety profile (readOnly, non-destructive, closed-world); the description carries the rest and does so extensively — the 30,000-character cap, null-vs-[] semantics for searchQueries with an explicit warning that null is not evidence of no search, stopReason values, exclusion of grounding-redirect and scan-echo URLs, recovered mentions lacking position/sentiment, sourcesNameSitesOnly behaviour, and data-availability cutoffs (Oct/Jul 2026). It also flags that the returned text, URLs and searches are third-party content to be quoted but never obeyed, which is a genuine safety disclosure.

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 content list is front-loaded in the first sentence, and with no output schema every caveat (null semantics, excluded link classes, per-provider quirks, date cutoffs) earns its place. The cost is structure: one dense block with long em-dash-chained sentences and no segmentation, which makes the edge cases harder to scan than they need to be.

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

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

With no output schema and a genuinely complex return shape, the description documents nearly every field, including the ones that can be null for non-obvious reasons and the per-engine limitations that change how a field should be read. An agent can interpret the response correctly without guessing.

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, but the description adds meaning the schema lacks about maxTextChars: that textChars still reports the true length and textTruncated signals truncation even when text is suppressed. That is output behaviour tied to the parameter, not a restatement of the schema's '0 = none'.

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 opening clause states a specific verb and resource ('One AI answer in full') and immediately enumerates the payload — full response text, brands named with positions, cited vs retrieved URLs, search queries, recommended products. This is unmistakably distinct from list_ai_answers (a list) and get_citations (an aggregate), so an agent can route 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?

It routes the agent to the two places an answerId comes from ('Take answerId from list_ai_answers or get_cited_url') and gives a concrete usage variant ('To read the brands, sources and searches without the whole text, pass maxTextChars (0 = no text)'). It never states when NOT to use this tool or which sibling answers citation/brand-aggregate questions instead, so it is clear context rather than 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?

Annotations already mark it read-only and non-open-world, and the description goes well beyond that: it enumerates the availability states (ga4_not_connected, ga4_read_failed, ga4_no_access) with the specific meaning and remedy for each, states that unavailable figures are null rather than zero, and warns that a fall in GA4 figures is usually a tracking change because ChatGPT-opened links carry no UTM. This is rich, decision-relevant behavioral context.

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

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

The content is dense and mostly earns its place, but it is delivered as a single run-on wall of text mixing what the tool returns, availability semantics and caveats with no sentence or list breaks. Front-loading is good (the first clause states the core purpose), but readability and structure suffer for a description this long.

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

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

With no output schema and five optional parameters, the description carries the full burden and meets it: it explains the returned figures (per-day visibility, sessions, conversions, revenue, totals, rate with margin, correlation window and interval) plus the null-handling and caveats. An agent has everything needed to call and interpret it.

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 five parameters (days, metric, source, clientId, projectId) are already documented in the schema, including enum meanings. The description reinforces what 'the chosen metric' means for the correlation but adds no syntax or format detail beyond the schema, 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?

The description states a specific verb and resource: it returns a project's AI visibility alongside the GA4-sourced visits, conversions and revenue that AI assistants send to the site, broken into per-day, window totals, rate comparison and correlation. That is far more concrete than the bare name 'get_ai_attribution'. It does not explicitly differentiate itself from siblings like get_ai_visibility_metrics or get_visibility_trend, so it stops short of a 5.

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

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

The description gives interpretive guidance (read GA4 figures next to visibility, never alone) but never states when to choose this tool over the many sibling analytics tools. The edge-case handling for GA4 availability is useful context, yet the when-to-use-vs-alternative dimension is only implied.

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

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

Annotations cover only the safety profile, and the description adds substantial behavior beyond them: ~60,000-character payloads, 500-row truncation with a truncated flag, answer-shortfall notes, and measurementIncidents naming an engine with incompletely captured answers plus the instruction to never present a drop there as a visibility loss. It also discloses that figures are as of latestScanDay and cover earned mentions only.

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

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

Front-loaded with purpose, and most sentences carry substantive content, but it is a dense, run-on paragraph mixing scoping, source semantics, paging, truncation, and data-quality caveats. Structure is weak and it takes effort to extract the operational instructions.

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 10-parameter tool with no output schema, the description covers the returned structure (pooled.brands fields, clientByEngine), payload size, paging contract, truncation, and measurement-incident caveats. An agent has what it needs to call and interpret the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real interpretation value: how pooled values are computed (visibility = mentionedAnswers ÷ answers, margin in percentage points, sentiment 50 = neutral), the instruction never to average snapshot percentages, how source blending resolves duplicates, and nextOffset/limit paging. This exceeds what the schema alone conveys.

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: returns how visible a project's brand and competitors are in AI answers over a UTC-day window, with default/max range. It names related concepts (pooled.brands, source, engineLabel) but does not explicitly differentiate itself from siblings like get_visibility_trend or get_brand_perception, which share the same domain.

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 concrete routing: pass summary:true for the answer itself vs limit/offset to page rows, and states movements are only real when get_signals raised them. It lacks explicit when-not-to-use guidance (e.g., versus get_visibility_trend or get_brand_perception), but the operational conditions it does give are 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 cover the safety profile (readOnly, non-destructive, closed-world), and the description goes well beyond them: it explains the sentiment scoring mechanics (−1..+1 per mention mapped to 0–100 with 50 = neutral), that sentiment is brand-level only, that attributedMentions is the real denominator, that brands under ~5 mentions are unreliable, and that fact-check analyses are returned only if present. That is exactly the extra behavioral context 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 payload description is front-loaded and dense with zero filler, but the long parenthetical honesty clauses (especially the sentiment formula) make it heavier than it needs to be for a single paragraph. Still, every clause carries information and nothing is 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?

No output schema exists, so the description must carry the return-value burden, and it largely does by listing the returned components and their semantics. It omits return shape/pagination/limit details, which are minor for a read-only analytical tool but keep it short of complete.

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

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

Schema description coverage is 100%, so the four parameters (days, engine, clientId, projectId) are fully documented in the schema itself, including the engine fallback behavior. The description adds no parameter-level syntax or format detail beyond that, 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?

The description states a specific resource (brand perception terms AI models use per tracked brand) and enumerates the exact payload: clustered terms with counts and per-brand share, distinctive terms, brand-level sentiment, cited pages, and stored fact-check/objection analyses. This is far more specific than the sibling metrics tools (get_ai_visibility_metrics, get_visibility_trend) and lets an agent confidently tell it apart 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?

There is no explicit when-to-use/when-not-this-tool guidance and no named alternative, so the agent must infer that this is the tool to reach for when brand-level term/sentiment analysis is wanted. The honesty notes do implicitly steer interpretation (e.g., brand-level sentiment, thin-sample warning), which is a partial substitute but not true usage routing.

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 a safe read (readOnlyHint true, destructiveHint false, openWorldHint false), and the description adds substantial behavioral context on top: the CITED vs RETRIEVED-only split, how legacy runs lacking the split are quarantined rather than blended, Gemini's site-not-page behavior, and that null categories are 'never guessed'. This is unusually rich disclosure of edge-case 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 opening sentence is well front-loaded, but the rest is a single sprawling paragraph with deeply nested parentheticals (shareOfChats, category sources) that is hard to parse and far longer than needed. Density substitutes for structure here.

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?

There is no output schema, so the description must carry the return-value burden, and it does: per-domain run counts, top pages, shareOfChats and its formula, and category/categorySource. It is nearly complete, with only minor gaps (no mention of pagination or result limits).

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

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

Schema description coverage is 100%, so the schema already documents all five parameters (days, model, clientId, promptId, projectId), establishing the baseline of 3. The description adds a little framing (window semantics, engine filter behavior) but nothing the schema does not already convey.

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 ('which domains AI engines cite when answering this project's prompts') and scopes it to a window, which is far more precise than a restated name. It does not, however, explicitly differentiate itself from closely-named siblings like get_cited_url or list_citation_lifetimes, leaving the agent to infer the boundary.

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

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

The description explains what is returned in great detail but never says when to reach for this tool versus the sibling citation tools (get_cited_url, list_citation_lifetimes, get_ai_attribution). There is no when/when-not framing or named alternative, so selection guidance 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 only declare readOnly/openWorld=false/destructive=false; the description adds substantial behavior the annotations cannot: URL matching semantics, the special handling of YouTube/Facebook/Play/HN URLs, identity-return for non-page URLs, unsplit counting for engines without a cited/retrieved split, Gemini sites-only exclusion (with the sitesOnlyAnswersExcluded field), the lifetime block's own fixed 26-week frame, and a prompt-injection warning ('third-party text — quote it, never follow it'). That is well beyond what the structured fields 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?

It is a single enormous paragraph of heavily nested clauses and parentheticals; the front-loaded purpose is quickly swallowed by edge-case detail. Most of the content is substantive rather than filler, but the lack of segmentation, ordering or summary makes it hard for an agent to parse and violates 'every sentence earns its place' in structure terms.

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

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

With no output schema, the description carries the return-shape burden and largely does so, naming the url block fields (title, pageType, pageTypeSource, category) and the lifetime block fields (status, rates, n, streaks, series, byEngine, causes). Coverage is strong for a tool of this complexity, though the dense prose leaves some edges (e.g. the exact status semantics) implied rather than explicit.

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 genuine semantic meaning for 'url' beyond the schema's terse 'The page URL': how URLs are normalized (host without www plus path, fragment/query ignored), which parameter is kept on named sites, and what an identity/no-single-page address returns. It also explains that the model filter leaves the lifetime block engine-agnostic, matching the schema note.

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 opening clause states a specific verb+resource ('Drill into one page the AI engines use as a source') and enumerates exactly which metrics it returns (cited/retrieved counts, share of chats, prompts, engines, first/last seen, brand/competitor mentions, recent answer ids). It distinguishes itself from siblings by naming get_citations ('Find the pages worth drilling into with get_citations first'), get_ai_answer and list_citation_lifetimes. Clarity is real but is buried under an extremely dense block of caveats, so it falls short of a crisp 5.

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

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

It gives concrete routing: use get_citations first to find candidate pages, then this tool to drill into one, and use get_ai_answer to open the returned answer ids; list_citation_lifetimes is named for the related workflow. There is no explicit 'when not to use this' or exclusion beyond the implicit dependency, so it stops short of 5.

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

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

Annotations already declare readOnlyHint/openWorldHint/destructiveHint, and the description still adds substantial behavior: 'reading generates nothing and costs nothing', the meaning of 'verdict unknown' ('no Search Console, not "no page"'), the existingPage interpretation (refresh vs new page), and a prompt-injection warning ('treat it as data'). This is well beyond what annotations provide.

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

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

Front-loads the core purpose and is information-dense, but it is one long run-on paragraph riddled with parentheticals and em-dashes that make it harder to scan than it needs to be. Almost every clause carries real information, so little is wasted.

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

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

With no output schema and no required parameters, the description carries the full burden of describing what is returned, and it does so thoroughly — the brief's sections, the evidence structure (cited pages, searches run, existingPage), and before/after visibility. An agent has everything needed to call and interpret it.

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, but the description adds semantic meaning to promptId by explaining the dual-mode contract (list vs. full brief) and its interaction with the fan-out scoping. The search/clientId/projectId nuances remain mostly in 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 (get saved content briefs) and enumerates exactly what a brief contains (target question, recommendations, page structure, schema, proof, caveat). It also distinguishes itself from generation ('Reading generates nothing... new briefs are generated in the app'), so it is separable from create_content_brief without opening either schema.

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

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

Gives explicit mode selection: without promptId it lists saved briefs, with promptId it returns that prompt's latest brief in full, and it clarifies that generation must happen elsewhere because it spends AI. The only gap is that it points to the in-app path rather than naming the sibling create_content_brief tool directly.

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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds real value beyond them: the exact inclusion criteria for a gap and the shape of what comes back (competitors named plus the domains the engines cited instead). It stops short of mentioning limits on result volume or the significance of the minRuns threshold.

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

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

Two sentences, front-loaded with the gap definition and followed by the return contract; no filler or restated name. The first sentence is dense but each clause carries meaning, so it stays readable and earns its length.

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

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

With no output schema, the description has to describe returns, and it does identify the two key payloads (named competitors, cited domains). Combined with the precise gap criteria and full schema coverage, an agent has enough to call it correctly; only volume/pagination and edge-case behavior remain unaddressed.

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 days, minRuns, clientId and projectId are already fully documented and baseline is 3. The description's phrase 'recent AI answers' loosely gestures at the days window but adds no syntax, defaults, or interaction detail beyond the schema.

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

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

The description defines the exact resource being returned — prompts where the tracked brand is absent from every recent AI answer while competitors are named — rather than vaguely saying 'get gaps'. That operational definition lets an agent distinguish this from adjacent reads like get_content_brief, get_prompt_details, or get_ai_visibility_metrics without opening schemas.

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

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

Usage is implied through the tie-in to the in-app Content Brief generator and the note that each gap can become an evidence-grounded brief, which hints at the get_content_gaps → create_content_brief workflow. However, it never states when to prefer this over other visibility diagnostics (get_insights, get_ai_attribution) nor any preconditions, so guidance remains inferred rather than explicit.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description goes well beyond that: it distinguishes RAW vs 'Real' block counts, explains that null means 'unknown, never 0%', flags what is deliberately excluded from topPaths, and adds the honesty caveat that crawler visits show access, not citations. With no output schema, this interpretive context is genuinely additive, though it focuses on result semantics more than on side effects or prerequisites.

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 text is a single sprawling run-on of several hundred words with no paragraphing or hierarchy, so the essential purpose is buried under field-level detail. Most sentences do carry information that has no other home (there is no output schema), but the lack of structure makes it hard to scan and front-loading is essentially absent.

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

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

With no output schema, the description carries the full burden of explaining the return shape, and it does so exhaustively: purpose split, IP verification, real vs raw block counts, wafAlert levels, scanner/impostor exclusions, hostingPlaceholder levels, markdownPreference, and the optional sections breakdown. Interpretive caveats (null means unknown) are included, making it complete enough for an agent to read the results 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 description coverage is 100%, so days, clientId, projectId and sections are already documented in the schema; the baseline is 3. The description does expand meaning for the sections flag by enumerating what the grouped output contains (rules, homepage, first path segment, 'other' row), which is marginally more than the schema states, but the other three parameters get no added description-level clarification.

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 opening clause gives a specific verb and resource: 'Get AI-crawler analytics from the project's forwarded server logs'. It is clearly distinguishable from siblings like get_ai_visibility_metrics or get_citations by domain (server-log crawler traffic). However, it never names an alternative tool, so the differentiation is by description alone rather than explicit routing.

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?

There is no explicit when-to-use or when-not-to-use guidance and no named alternatives among the many get_* siblings. The 'HONESTY' note tells the agent how to interpret crawler access vs citations, which is useful framing, but it is interpretation guidance rather than tool-selection guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description nonetheless adds real behavioral context beyond that — the workspace/project prerequisite, the fact that these are API conversations with no account or personalisation, and explicit data-semantics rules (searchQueries [] means no search ran, null means no list came back; nothing is ever counted as 0; grounding-redirect links are excluded with a count). That is substantive disclosure, though it is framed as return-value semantics rather than operational behavior.

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

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

Front-loading is good: the first sentence states the resource and scope before any detail. However, the body is a single enormous paragraph with deeply nested parentheticals that is hard to parse. Because no output schema exists, much of the length is load-bearing, but bullet-style structuring of the return blocks would have made the same content far cheaper to read.

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

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

With no output schema and seven optional parameters, the description carries the full documentation burden and does so thoroughly: it enumerates survival, insights, searchStates, brandBaseline, slot, sources, searches and list, plus the {part, of, rate} ratio contract and the of<10 quoting rule. An agent could call this correctly and interpret the result; the only gap is that the alternate conversationId mode's full shape is described in passing.

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. The description does add a little meaning — conversationId is a 'list row's turn1Id' and returns one conversation in full instead of aggregates — but the engine and window semantics are already carried by the schema, so the net addition is marginal.

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 opening sentence names a specific verb and resource — 'Get Follow-up Survival for a project' — and defines the scenario (a buyer narrowing the question in the same conversation) precisely enough that an agent knows this is a follow-up-survival analytics tool, not a generic insights call. It never names or contrasts a sibling (get_insights, get_query_fanouts, get_citations), so the 5-level criterion of explicit sibling differentiation is unmet.

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 final sentence gives a hard prerequisite ('Requires Follow-up Survival to be switched on for the workspace and the project'), and the conversationId sentence describes an alternate single-conversation mode. But there is no guidance on when to pick this over sibling analytics tools such as get_insights or get_query_fanouts, so the agent must infer the boundary.

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 readOnly/destructive/openWorld, so the description carries the real burden and does so in depth: it explains that firewallAccess is null on inconclusive probes, what `layer` values mean and why the fix targets that layer not robots.txt, what blockedOn/contentOnlyBlocked/contentCloudflareDefault signify, and that a partial/failed live-reachability check depends on the Cloudflare default pattern.

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 purpose is front-loaded in the first clause, but the remainder is a single run-on parenthetical block of roughly 500 words chained by semicolons, which is hard to scan. Most content is non-redundant, yet it is not appropriately sized or structured for a tool description.

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

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

With no output schema, the description must carry return-value semantics, and it does: it names scoreNote, firewallAccess rows, layer, contentUrl, blockedOn, contentOnlyBlocked and contentCloudflareDefault, plus the methodology caveat that the probe does not originate from the crawler's published IP ranges. Nothing needed to interpret results 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 description coverage is 100%, so the schema already documents clientId, projectId and includePages; the baseline is 3. The description only lightly extends includePages ('per-sampled-page drill-down') beyond the schema's own text.

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

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

Names a specific verb+resource (the latest technical GEO Audit for a project's domain) and enumerates its contents: composite score/band, per-category results, AI insights, Agent Readiness sub-score, firewallAccess. It also explicitly scopes what the score does NOT measure, which cleanly separates it from get_ai_visibility_metrics.

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

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

It routes the agent away for visibility questions ('measure visibility with get_ai_visibility_metrics') and gives the includePages trigger for the per-page drill-down. It never states when to use this read tool versus the run_geo_audit sibling, so the read-vs-create distinction 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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: the value is refreshed by a scheduled job (updatedAt), money is in the client's main ad-account currency unconverted, and the tool changes nothing. These are genuine behavioral disclosures, though much of the text is return-value interpretation rather than tool behavior.

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

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

The purpose is front-loaded, which is good, but the description then runs to roughly 380 words of dense, semicolon-chained clauses packed into a single unstructured block. Much of the content is justified by the absence of an output schema, but the winnowing and formatting are poor, hurting scanability.

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

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

With no output schema, the description carries the full burden of explaining return values and it does so exhaustively: null/NO DATA semantics, status definitions (on_track, at_risk, too_early, no_target, no_data), the ROAS coverage rule, and the ratio-pairing rule for CPA/Cost per lead. An agent has everything needed to call it and interpret the result.

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 with 100% schema description coverage ('Only this client's goals'), so the schema already documents it. The description says 'per client' but adds no semantics about what happens when clientId is omitted (all clients vs. default), so it does not meaningfully exceed the schema 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?

The opening sentence states a specific verb+resource+scope: retrieving the Goals on the Monitoring page, per client, for one paid-ads metric. It also names what it is not ('Does not cover AI-visibility metrics', 'changes nothing (set_goal does)'), so it can be told apart from siblings. However, the core purpose is buried under a dense wall of output semantics, making it harder to extract at a glance than the intent warrants.

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 closing sentence gives an explicit exclusion (AI-visibility metrics → get_ai_visibility_metrics) and an alternative for mutation (set_goal), which is useful routing. But it never states the positive condition for choosing this tool (when an agent should fetch goals rather than, say, get_report_data or get_insights), leaving the 'when' 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?

Beyond the readOnly/openWorld/destructive annotations, it discloses material behavior: results are computed at call time from the last 30 whole UTC days plus a live website check, the 10-brand cap and ordering, and the priority rules (data-based action is high only with 10+ answers behind it; llms.txt always low). It also tells the agent to quote the observation wording as-is rather than promise an effect.

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

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

The output content is front-loaded in the first sentence and every clause carries distinct information (fields, priority logic, computation window, scoping, exclusions). It is dense and could be broken into bullets for scanability, but there is little genuine filler for a tool of this complexity.

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

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

With no output schema and a rich, multi-field return, the description supplies the return shape, the computation window, the brand-count limit, and the scoping rules. An agent has enough to call it correctly and interpret results without further sources.

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 routing semantics the schema does not: the projectId-vs-clientId either/or and the 'omit both for the agency-wide page' behavior, plus what priority filtering selects. It does not expand on the source enum, so it is not a full 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?

It names the exact resource (the prioritised actions on the AI Visibility Insights page) and enumerates the action families and their fields (priority, rationale, affected prompt count, domain, engines). It explicitly distinguishes itself from the two nearest siblings, get_signals and get_content_gaps, so an agent can route 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?

It states the selection rules explicitly: pass projectId or clientId for one brand's Insights tab, omit both for the agency page across every brand with a scan (capped at 10, most-recent first). It also names the alternatives it is not (get_signals for detected changes over time, get_content_gaps for the prompt-gap list).

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 a safe read (readOnlyHint=true, destructiveHint=false), so the description is free to add real value, which it does by disambiguating the two citation fields: runsCiting counts runs that cited a domain at least once, while citations counts total citations including repeats. That is meaningful semantics an agent cannot infer from the 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?

Front-loaded with the purpose, then a tight enumeration of return contents, ending with the imperative call instruction. The single long sentence is dense but every clause (especially the runsCiting vs citations parenthetical) earns its place; only the packaging, not the length, is slightly heavy.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so across all four content areas. It doesn't describe the overall response structure or how sections are keyed, which would be expected for a multi-section detail payload, but 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 both parameters are already documented, including the days default of 30 and max of 180. The description reinforces the window concept ('pooled visibility over a window') and re-states where promptId comes from, but adds no format or edge-case detail beyond the schema, 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?

Names a specific verb and resource ('Full detail for one tracked prompt') and then enumerates exactly what that detail contains: per-engine pooled visibility, competitor mentions with counts, cited domains, and the freshest answer excerpt. An agent can distinguish this from list_prompts or get_citations without inspecting 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?

Provides a clear prerequisite and routing hint ('Pass the promptId from list_prompts'), which tells the agent this is a drill-down from the listing tool. It stops short of naming when-not-to-use alternatives such as get_citations or get_ai_visibility_metrics, which cover overlapping data at a different scope.

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 assert a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description goes far beyond them: null semantics for gsc, gscRead error states including the auth_error reconnection need, coverage limits (capture start, engines that never expose searches), and the fundamental distinction between unknown and absent. This is exactly the behavioral context annotations cannot carry.

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

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

The purpose is front-loaded and much of the content is genuinely necessary given the complexity, but the body is a single enormous block of deeply nested parentheticals that is hard to parse and pushes past practical conciseness. Structure (breaks, grouping by source/filter/signal) would materially improve usability without losing content.

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

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

For a tool with 9 parameters, no output schema, and two distinct data sources, the description covers row shape (provenance, signals, gsc, brandsInSearches, sequences), field semantics, filters, and source-specific caveats. Given there is no output schema, the return-value explanation it provides is appropriately thorough.

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 it: it clarifies that promptType is the prompt's category and not a reading of the search, that peecQueryKind is Peec's own classification rather than a prompt type, and that fanoutSource selects whose capture and can never be pooled. These are interpretation rules the schema alone doesn't convey.

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 opening sentence gives a precise verb and resource — the web searches each AI model ran via the provider's API before answering tracked prompts — and immediately scopes it by ruling out 'a transcript of a user's ChatGPT session.' It further distinguishes this capture from the imported Peec source, so an agent can separate it from siblings like get_citations or get_ai_answer.

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

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

The description is explicit about when filters apply and when they don't (promptType/tag/Search Console/citations have no meaning for Peec and are 'ignored there'), and it instructs the agent to compare the two sources side by side and never pool them. It does not, however, route the agent to a named alternative sibling tool for adjacent questions, so it stops short of full 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured fields. The description adds useful context by describing the returned evidence (result counts vs. requested, a repeat-search link, cost), but discloses nothing about auth requirements, rate limits, or edge-case behavior. With annotations carrying the behavioral load, a 3 is appropriate.

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

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

Two sentences, front-loaded with the core concept and then the usage cue. The first sentence is a dense enumeration of return fields, which is informative but somewhat hard to scan as a single run-on clause. Still, it is appropriately sized and each element 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?

No output schema exists, so the description bears the burden of conveying return values — and it does so thoroughly (results list, tracked domain positions, position history, cost, repeat-search link). Combined with annotations covering safety and a complete schema, an agent has enough to call it correctly. The only gap is sibling routing.

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 three parameters (rows, checkId, clientId) are already documented in the schema, including the rows default of 30 and the note that tracked-domain rows are always included. The description adds no parameter-level detail beyond this, 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?

The description opens with a clear, specific framing — 'the evidence behind one ranking' — and enumerates exactly what that evidence contains (search results, tracked domain positions, position history, cost). This distinguishes it from the sibling get_rankings, which presumably reports positions rather than the raw backing. It loses a point only because it describes the payload as a noun phrase rather than leading with an explicit retrieval verb.

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

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

It gives concrete usage scenarios: answer 'why does it say position 9?' or 'why was it not found?'. That is a strong, specific context cue. However, it never names the obvious alternative (get_rankings) or states when NOT to reach for this tool, so routing against siblings is left implicit.

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 cover the safety profile (readOnly, non-destructive, closed-world), and the description adds real behavior beyond them: pagination of rows, exactly what the summary aggregates, the 7/28/90-day comparison rule and the fallback to the last comparable check, and the fact that volume data flows through the workspace's own DataForSEO account or Rank Tracker budget. No rate limits or failure modes are described, keeping it below 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?

The purpose is front-loaded in the first clause, which is good, but the body is a very dense run-on paragraph packing seven-plus ideas into a few enormous sentences. Nothing is truly wasted, yet the structure makes it hard to scan and would benefit from being broken up.

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

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

With no output schema, the description must explain return values, and it does so thoroughly: per-keyword columns, the engine/device-scoped summary, tag splits, brand splits, Keyword Planner volume ranges, and competitor positions. It is complete enough to call correctly, with only minor gaps around response shape and pagination totals.

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. The description reinforces filter semantics ('Narrows the summary too', 'Outside includes not found' style context for comparisons) but adds little that isn't already in the schema descriptions, and restates verbatim for several parameters.

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 opening names a concrete resource and scope: 'A client's keyword rankings in Google and Bing', then enumerates the exact per-keyword and summary figures returned. An agent can tell this is the rankings-report tool rather than a setup or config tool. However, it never explicitly distinguishes itself from close siblings like get_ranking_evidence or refresh_rankings, so it stops short of a 5.

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

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

It gives useful invocation context — the summary covers 'every active keyword of the list, narrowed by tag, search and branded ... and by nothing else; rows are paged', and it points to get_rank_tracking_setup for the default column. But it never states when to use this versus alternative ranking tools (get_ranking_evidence, refresh_rankings) or any prerequisites, so usage is only implied.

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

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

Annotations already declare readOnly/non-destructive/non-open, and the description adds real value on top: the login is masked and the password is never returned (security posture), plus the two billing models (workspace account vs. managed budget with account.source = "managed"). It does not describe pagination or refresh semantics, so it is not exhaustive.

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 every clause maps to a distinct returned field with no filler. It is one very long comma-chained sentence, which is dense but not wasteful.

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?

There is no output schema, so the description properly carries the return-value burden by enumerating the configuration fields (account mode, domains, schedule, engines/devices, spend). Nothing an agent needs to decide or call the 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?

Single clientId parameter at 100% schema coverage, and the schema already documents it as coming from list_clients. The description adds no syntax or format detail beyond the schema, 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?

The description states precisely what is retrieved – the rank-tracking configuration for a client (engine/budget mode, domains, schedule, engines/devices, cost). This clearly distinguishes it from get_rankings (positions) and set_rank_schedule (mutation), though it never names a sibling explicitly.

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?

Ends with an explicit prerequisite: "Read this before adding keywords or starting a refresh." That tells the agent when to reach for it in a workflow, but it names no alternative read tool and gives no when-not condition.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered without contradiction. The description adds only the mild context that the payload is a config/definition rather than report data; it says nothing about auth requirements or behavior for an unknown id.

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?

One compact sentence with the resource and lookup key front-loaded, the parenthetical covering the returned fields without padding. Nothing to trim.

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

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

With no output schema, the description usefully enumerates what the definition contains, which is exactly what an agent needs to decide it should call this before get_report_data. Minor gaps remain: no note on missing-id behavior and no explicit tie to list_reports or create_report as the id source.

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

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

Schema coverage is 100% for the single reportId parameter, so the schema already carries the documentation burden. 'By id' merely restates the parameter; no format, source, or lookup-failure semantics are added, 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?

States a specific verb (get), resource (a single report's definition), and lookup key (by id), and enumerates the returned fields (name, type, widget layout, date-range config). The word 'definition' implicitly separates it from get_report_data and the singular scope separates it from list_reports.

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 phrasing 'a single report's definition ... by id' implies when this is appropriate (you already have an id and want the report's config, not its data), but no alternative is named and no prerequisite for obtaining a reportId is given. Usage is left to inference from the siblings list.

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 cover the safe-read profile (readOnlyHint, destructiveHint false, openWorldHint false), yet the description discloses a large amount of non-obvious behavior: unavailable widgets return null with _meta.unavailable (never zero), gads_not_summable / not_summable donuts have no slices by design, memoryExcluded/fromMemory answers excluded from both numerator and denominator, citationCountsMissing, withinMargin cells to call unchanged, and untrustedContent third-party text. This is far beyond what annotations provide.

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

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

The purpose is front-loaded in the first sentence, but what follows is a single enormous run-on paragraph spanning dozens of edge cases and cross-referencing many _meta fields and aiNote behaviors. Much of it is output-interpretation guidance that crowds the selection-relevant content and makes the description hard to scan, even if individual facts are useful.

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

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

With no output schema and a highly complex, multi-source reporting tool, the description carries the full burden of explaining return shapes, null semantics, and special widget cases. It does so comprehensively, covering unavailable data, not-summable donuts, exclusion flags, sparklines, and per-source caveats.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: datePreset/comparePreset default to the report's saved config, widgetIds should come from get_report, and brandFilter's effect on splittable widgets is spelled out. It stops short of 5 because most parameter detail duplicates the already-complete 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 up front: 'Assemble a report's LIVE data (KPIs, charts, tables) for a period', plus 'Pulls from the connected sources exactly like the app does'. It also names the sibling get_report as the source of widgetIds, so an agent can distinguish it from report-metadata and single-metric 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 concrete routing guidance: pass widgetIds for a single-table question because a 500-row table can reach ~90,000 characters, and points to update_report_settings for the Meta Ads exclusion case. It lacks explicit when-not-to-use guidance against the many sibling data tools (get_ai_visibility_metrics, get_insights, get_citations), so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description goes well beyond them: it defines waitingToStart semantics, explains that estimatedMinutesLeft is an estimate with two estimateBasis modes ('measured pace' vs 'queue position') and may be null, and contrasts background (server-advanced every few minutes) versus app-tab scans. This is exactly the runtime behavior an agent needs and 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?

Front-loaded with the returned fields before moving to estimate caveats and input sourcing. Every sentence carries information, but the closing sentence about a queued scan waiting for the running scan restates the earlier waitingToStart explanation, adding mild redundancy to an already long paragraph.

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?

There is no output schema, so the description carries the full burden of describing the return shape — and it does, enumerating status, completed/failed check counts, timestamps, last error or budget pause, waitingToStart, estimatedMinutesLeft, and estimateBasis. For a zero-required-parameter status tool, nothing an agent needs to call it or interpret the result 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, but the description adds disambiguation the schema lacks: jobId comes from run_scan, and projectId/clientId resolve to 'that project's most recent scan,' with clientId implicitly selecting the newest AI-Visibility project. It clarifies the precedence between the three optional identifiers, though it never states what happens if multiple or none are supplied.

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 — reporting the progress/status of an AI-visibility scan — and immediately enumerates the fields it returns (status values, checks finished/failed, timestamps, last error). It is clearly distinguishable from the sibling run_scan, which starts a scan rather than reporting on one.

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 invocation context: 'Pass jobId from run_scan, or projectId/clientId for that project's most recent scan,' which tells the agent exactly how to obtain the identifier. It also explains queued-scan behavior so the agent knows a queued result is normal, not an error. It stops short of naming when NOT to use this versus alternatives such as get_ai_visibility_metrics, so it is a strong 4 rather than a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond that: figures come from real shopping-scan runs, a no-hit product reads 0% over the real run count, and win rate is null until a decisive run exists — real edge-case disclosure.

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 purpose, then defines each metric and the fallback id behavior in a single dense paragraph. It is long but nearly every clause adds information; minor trimming of the metric definitions is possible but not warranted.

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?

No output schema exists, so the description must explain returns — and it does, defining recommendation rate with standard error, head-to-head win rate, and discoveries. Combined with the edge-case notes, an agent has everything needed to call and interpret the tool.

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

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

Schema coverage is 100%, so the schema already documents both parameters, including that clientId resolves to the newest project. The description only restates that either id can be passed, adding marginal meaning. Baseline 3 is appropriate when the schema carries the load.

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 product-level AI SHOPPING visibility') and precisely scopes the resource to product-level shopping data, distinguishing it from siblings like get_ai_visibility_metrics or get_visibility_trend. An agent can tell what it returns 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?

Says 'Pass a projectId or clientId,' which clarifies the input choice, but gives no explicit when-to-use vs alternatives such as get_ai_visibility_metrics or get_visibility_trend. Usage is only implied by the 'shopping' framing, so it lands at minimum-viable.

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 cover the safety profile (readOnlyHint/openWorldHint/destructiveHint), yet the description adds substantial context beyond them: which signal types exist, the severity/n/confidence triad, the distinct confidenceKind values ('tested' vs 'fact' vs 'none'), and the non-obvious fact that title/detail are stored English words while text is re-generated at read time. The evidence-vs-no-evidence behavior of signalId is also disclosed, which directly affects how the caller should invoke it.

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

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

The description is an unstructured wall of text with no line breaks or bullets, and a large share of it is deep detection-logic detail (95%/99% thresholds, 15%/40% fall bars, pooled 14-vs-28-day windows, Student's t with prompts−1 degrees of freedom) that reads like pipeline documentation rather than selection guidance. The purpose is front-loaded, but the body is heavily over-sized for a tool-selection description.

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

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

With no output schema present, the description carries the full burden and largely does so: it enumerates the returned fields (severity, n, nUnit, confidence, confidenceKind, windows, title/detail/text) and explains their semantics, including how windows is populated per signal type. An agent has enough to interpret the response without an output schema.

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

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

Schema description coverage is 100%, so the schema already documents limit, status, clientId and signalId, making 3 the baseline. The description adds only marginal meaning for signalId by explaining what the non-signalId path returns; limit, status and clientId receive no extra interpretation in the description text.

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

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

The description clearly establishes the resource: it is the 'CrunchJunkie Signals inbox' of 'detected events and standing conditions,' and the final sentence states the concrete return behavior (newest matching signals, or one signal with full evidence). It does not, however, explicitly differentiate itself from adjacent sibling tools such as get_insights or get_ai_visibility_metrics, leaving the boundary to inference.

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?

There is real usage guidance for the signalId branch ('Pass signalId for one signal WITH its full evidence; otherwise returns the newest matching signals without evidence payloads'), which tells the agent when to pick each mode. But there is no guidance on when to reach for this inbox versus sibling read tools, nor any mention of pairing it with resolve_signal, so usage is largely implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds substantial context beyond that – weighted check accounting, BYOK scans excluded from the allowance, ESTIMATE caveats with null handling, and the non-metered-tier behavior that returns no figures rather than zeros. It does not cover auth requirements or freshness/rate-limit behavior beyond pricesLastChecked.

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

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

Purpose is front-loaded, and every clause carries information, but the entire body is a single run-on sentence packed with nested parentheticals that is hard to parse. Detail is appropriate given no output schema, yet the structure is not disciplined.

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

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

With no output schema, the description carries the full burden of explaining returns and does so exhaustively – allowance numbers, BYOK estimate fields, checksBySurface, assistantMessages.bySurface, reset timing, and the non-metered edge case. It is complete for the tool's shape, though the density makes it harder to use than a structured enumeration would be.

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

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

The tool takes zero parameters, so the baseline is 4. The description explains scoping implicitly (current billing period, current workspace) rather than through inputs, and there is nothing in the schema left to clarify.

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+scope: "The workspace's Managed-AI scan allowance for the current billing period." An agent can immediately distinguish this billing/quota tool from the metric-oriented siblings (get_ai_visibility_metrics, get_insights), and the follow-on enumeration of what the payload contains reinforces the unique purpose.

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

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

Provides an explicit workflow trigger: "Check it before suggesting more prompts, engines or passes per prompt," plus the fallback condition for non-metered tiers. It does not name an alternative sibling or state when NOT to call it, so it stops short of a 5.

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

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

Annotations only cover the safety profile (readOnlyHint, destructiveHint false, closed-world); the description adds substantial behavior beyond that: exact pooling formulas, null-vs-zero semantics, the meaning and lifecycle of measurementIncidents, and explicit statistical caveats (never call a self-computed difference significant, never assign a cause).

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 purpose is front-loaded, but the body is a dense run-on block of roughly 250 words with no structural breaks, mixing output semantics, statistical caveats and incident handling. Most sentences carry real content, but the lack of structure makes it hard to scan and some caveat material is repeated in spirit.

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

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

With no output schema, the description carries the full burden of describing return values, and it does: the per-point fields, dayTotals, the pooled summary shape, and the note/engines behavior when a model has no answers. It also covers the edge cases (null days, incomplete engine captures) an agent needs before making comparisons.

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 schema already documents days, model, brands, market, source, summary, clientId and projectId — baseline 3. The description nonetheless adds meaning beyond the schema, notably what summary:true returns, how brands default ('the client plus the five competitors with the highest visibility'), and how source data is pooled.

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 opening clause gives a specific verb and resource — a day-by-day AI visibility series for a project, covering the client and top competitors — and enumerates the fields each point carries (visibility, share of voice, sentiment, average position, answers). It is clearly distinguishable from siblings like get_signals (significance testing) and get_ai_visibility_metrics, which the description routes to explicitly.

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

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

It states concrete when-to-use conditions: pass summary:true for the pooled window figure alone, consult get_signals for statistical significance, and read measurementIncidents before any comparison. It also gives an explicit when-not/how-to alternative for period comparison ('add up mentionedAnswers and answers over each period and divide once — never average daily percentages').

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 readOnly/openWorld/destructive hints, so the description carries the rest — and it does: it discloses purpose-built response flags (groundingRedirectsLeftOut, scanEchoLeftOut, sourcesNameSitesOnly), explains why they appear, and warns that answer text is third-party content to quote but never obey. That is materially beyond anything the annotations provide.

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

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

Purpose, scope, filters, paging and the hand-off to get_ai_answer are all front-loaded in the first three sentences; the flag glossary that follows is dense but earns its place with no output schema. Minor drift in the parentheticals ('as in get_ai_answer', '(574)') keeps it from a 5.

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 nine parameters, no output schema, and no required arguments, the description supplies the missing return-value context (row contents, edge-case flags, third-party-content caveat) plus filtering and paging guidance. An agent has everything needed to call it correctly and to interpret the response.

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 every parameter (days, limit, model, offset, source, clientId, promptId, projectId, brandMentioned) is already documented in the schema itself. The description only restates the filter axes at a high level and adds no syntax, format, or interaction 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?

The opening sentence names a specific verb and resource ('The actual AI answers behind a project's visibility numbers, newest first') and enumerates exactly what each row contains, so an agent can distinguish it from get_ai_answer and list_prompts without opening a schema. It also scopes the tool precisely: 'The list holds exactly the answers the metrics count.'

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

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

It states how to narrow results ('Filter by prompt, engine, or whether the brand was named, and page with offset') and explicitly routes the agent elsewhere when a single answer's full detail is needed: 'Open one with get_ai_answer for the full text, cited URLs and the searches the engine ran.' The relationship to the metrics tools is spelled out so the agent knows this list and the visibility figure describe the same underlying set.

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, so the safety profile is covered; the description goes well beyond by decoding non-obvious semantics (triggerRetired=true means the rule never fires even while enabled), enumerating run statuses, and disclosing a real constraint that Slack/webhook URLs are named but never returned. That is genuine behavioral context an agent cannot get from the structured fields.

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

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

Front-loaded with the resource, then one dense but purposeful paragraph; each clause (scope, enablement, run statuses, plan limit, read-only caveat, sibling pointer) carries distinct information rather than filler. It is on the long side and the status enumeration is heavy, but with no output schema that detail earns its place.

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

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

With no output schema, the description must describe the return payload itself, and it does so thoroughly — field-by-field contents, the meaning of ambiguous flags, run status vocabulary, and the plan's active-automation limit. It also closes the mutation gap and points to the sibling for a related query, leaving nothing an agent needs to call it 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 description coverage is 100% for both parameters, so the schema already documents clientId scoping and the runsPerAutomation default/max. The description only glancingly echoes scope ('one client or all') and recency ('its most recent runs') without adding format or boundary detail beyond the schema. Baseline 3 is appropriate when the schema carries the parameter burden.

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 ('The workspace's Automations (AI Visibility → Automations)') and then enumerates exactly what each returned item contains: trigger, actions, scope, enabled state, fire count, recent runs and statuses. It is unmistakably distinct from siblings like list_pending_approvals, which it names. An agent knows precisely what this returns without opening any schema.

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

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

Explicitly bounds the tool: 'Read-only: it does not create, edit, pause or run an automation — do that in the app', which tells the agent when NOT to use it and where the write path lives. It also routes a specific adjacent case ('For drafts waiting on a person, use list_pending_approvals'), giving a concrete alternative with its selecting condition.

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

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

Annotations already declare read-only/non-destructive, and the description adds substantial behavioral context beyond them: how the rate is computed (only eligible answers from the 8 weeks before), how unknown-source answers are excluded, sorting order, the ~10-minute refresh plus nightly check, the transient 'preparing' state, and Gemini's domain-only granularity. This is unusually rich disclosure.

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 purpose in the opening clause and every sentence carries substantive information — none is filler. However, it is delivered as one very dense paragraph with heavily nested parentheticals, which hurts scanability despite the lack of 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?

For a read-only listing tool with no output schema, the description covers what is returned (statuses, rates before/now, n, first/last citation, streaks), edge cases, sort order, freshness, and the drill-down path. An agent has everything needed to call and interpret it 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 description coverage is 100%, so all seven parameters — including scope, source, status, granularity — are already documented. The description mostly re-states the 'occasional is never listed' rule that the schema already contains, adding only the Gemini domain-granularity caveat, so it sits at the baseline for a fully documented 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 resource and outcome: which cited pages/domains are gaining or losing AI citations, expressed as a citation-lifetime status over the last 26 ISO weeks. Clearly distinguishable from siblings like get_cited_url (single-page drill-down) and get_citations (raw citation lists).

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?

Routes the agent explicitly to get_cited_url for drilling into one page and for reading the 'occasional' pages that are never listed. It also explains that 'no_recent_data' is not a loss, which prevents misuse. It does not, however, contrast this tool with other citation-listing siblings such as get_citations.

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/openWorldHint/destructiveHint, so the safety profile is covered. The description adds genuine behavioral value by disclosing the return shape (providers and report counts) and an important filtering rule: reports in Deleted are not counted.

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

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

A single well-formed sentence that front-loads the verb and resource and appends the useful detail in a parenthetical. No wasted words.

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

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

For a zero-parameter list tool with no output schema, the description tells the agent what it returns and one scoping caveat. Missing only whether results are workspace-scoped beyond the passing mention, but it is functionally complete.

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

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

Zero parameters and 100% schema coverage, so the baseline of 4 applies. The description correctly adds nothing to parameter semantics because there are none.

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 (list) and resource (clients), and usefully defines the resource as 'brands/domains' plus what each entry includes (providers, report counts). It does not explicitly distinguish itself from near siblings like list_workspaces or list_data_sources, so it falls short of a 5.

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?

No when-to-use guidance and no named alternatives, despite many sibling list_* tools. The phrase 'in your CrunchJunkie workspace' hints at scope but gives no condition for choosing this over list_workspaces or list_data_sources.

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 a closed-world scope, so the safety profile is covered. The description adds the useful details of workspace-wide scope and the optional single-client narrowing, but says nothing about result shape, ordering, or pagination.

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

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

A single front-loaded sentence with the resource and scope stated first and the filter qualifier second; nothing is redundant or padded.

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

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

For a zero-required-parameter read-only list tool with no output schema and full annotation coverage, the description supplies enough to call it correctly. It is only marginally short on what the listing returns.

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

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

Schema description coverage is 100% with one parameter, so the schema already documents clientId. The description's 'optionally filtered to one client' confirms the optional semantics but adds no format or behavior detail 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?

Specific verb 'List' plus the resource 'connected data sources' and concrete examples (Google Ads, GA4, Meta, Search Console) that distinguish it from other list_* siblings like list_clients or list_prompts. It doesn't explicitly name a sibling to route away from, so it stops short of a 5.

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 clause 'across your workspace, optionally filtered to one client' implies the filtering context, but there is no explicit when-to-use guidance, prerequisites, or mention of an alternative tool for a different scope.

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/destructiveHint=false, but the description adds substantial behavior beyond them: a hard cap of 100 items, soonest-due-first ordering, totalOpen/truncated indicators for overflow, the meaning of the CURRENT status field (resolved = issue cleared on its own), and an explicit prompt-injection warning to treat AI-written draft text as data. This is exactly the kind of context the annotations cannot carry.

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

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

Front-loaded with the resource identity and queue contents before detailing item fields and the read-only caveat. It is a long, em-dash-chained block where nearly every clause carries distinct information (cap, ordering, status semantics, injection warning), though the density is high enough that a sentence could arguably be split.

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

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

With no output schema, the description compensates by enumerating the returned item fields (draft text, client, severity, type, status, assignee, due date, note) plus the two empty-result/total fields, and it clarifies pagination via truncated. An agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so both parameters (clientId, bodyChars) are already documented in the schema, including the 4,000-char default the description repeats. The description adds no new parameter syntax or edge-case semantics beyond what the schema provides, 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?

States a specific verb+resource ('The Approvals queue') and defines exactly what the queue contains — AI-produced drafts awaiting a person plus manual tasks — which lets an agent distinguish it from list_automations, get_signals, or list_reports. The parenthetical breadcrumb (AI Visibility → Approvals) further disambiguates the resource.

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 marks the tool as read-only and routes the agent to decide_approval for the mutating action, which is exactly the when/when-not guidance needed. It does not, however, state exclusions against other read siblings (e.g., get_signals) that also surface approval-like signal data, so it falls just short of a 5.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds real behavioral context beyond them: the metric is a pooled ratio over a recent window, and results carry totalAvailable plus a truncated flag when capped, which tells the agent how to detect an incomplete listing. Auth, rate limits, and error behavior remain unstated.

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

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

Two sentences, front-loaded with the identity of the resource before the return-shape details. The first sentence is clause-heavy but every clause (metric definition, run counts, engines) describes something the caller receives. No filler or restatement of the tool name.

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

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

With no output schema, the description carries the return-value burden and largely discharges it: it names the visibility metric, run counts, engines, totalAvailable, and the truncated cap indicator. The gap is the absence of an explicit rule for what happens when neither projectId nor clientId is supplied, and no pagination detail beyond truncation.

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

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

Schema coverage is 100%, so the baseline is 3. The description exceeds it by stating the projectId/clientId either-or requirement, which the schema itself does not express (0 required params), and by clarifying the clientId path resolves to the newest AI-Visibility project. It adds no semantics for q, days, market, or activeOnly, but those are already documented in the schema.

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

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

The description names a specific verb and resource ("List the tracked AI-visibility prompts") and scopes it to a project or client, which cleanly separates it from suggest_prompts, translate_prompts, and add/remove_tracking_prompt. It also spells out the computed payload (pooled visibility = mentioned runs ÷ total runs), so an agent knows exactly what comes back. It does not explicitly name a sibling to defer to, which keeps it just short of a 5.

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?

"Pass projectId or clientId" is useful selection guidance, especially since the schema marks zero required parameters, so the description supplies the missing 'you must supply one of these' rule. However, there is no when-to-use versus when-not, and no routing to alternatives such as get_prompt_details or suggest_prompts. Usage is implied rather than stated.

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

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

Annotations already declare readOnly, non-destructive, non-open-world, so the safety profile is covered. The description adds genuinely useful behavior beyond that: Deleted/trash reports are excluded by default, and each returned report carries a deleted: true/false marker, plus the fact that ids are the return payload. No pagination or ordering details, though.

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

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

Two tight sentences: the primary action and return value come first, the trash/edge-case behavior second. No filler, and the most decision-relevant information (what you get back and how to use it) is 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?

There is no output schema, so the description correctly carries the return-value burden by naming report ids and the deleted flag. Combined with annotations covering safety, 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 description coverage is 100%, so both parameters are already documented in the schema. The description restates the clientId filter and the includeDeleted/trash semantics without adding format, id shape, or default behavior beyond what the schema states. 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 ('List the reports in your workspace') plus the scoping option (filter to one client), which cleanly separates it from create_report, get_report, and get_report_data. An agent can pick this tool 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?

Explicitly routes the agent forward: the returned ids are 'for get_report / get_report_data', so the list-then-fetch workflow is clear. It also states the includeDeleted condition for trashed reports. It stops short of stating when not to use this tool (e.g., when you already know the report id), so not a full 5.

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

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

Annotations already carry the safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower, yet the description adds substantial context: archived workspaces are frozen and every tool refuses there until an owner restores it, and the connector acts in only one workspace. It stops short of describing pagination or ordering.

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 correct verb+resource, but the middle is a single em-dash chain of six nested clauses that is heavy to parse. No sentence is wasted, yet the structure is more tangled than it needs to be.

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

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

With no output schema, the description must explain what comes back, and it does — down to the coveredBy billing relationship and the frozen-workspace semantics. An agent has everything it needs to call and interpret this tool.

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

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

Zero parameters, so the baseline is 4. The description instead characterizes the returned fields (role, plan, connector availability, write/AI-spend flags, archived state, coveredBy billing), which is genuinely useful detail rather than parameter guidance.

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 ('List the workspaces your account belongs to') and enumerates the returned fields, making clear it is the enumerating tool rather than the switching tool. The agent can instantly tell it apart from switch_workspace.

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 alternative: 'Use switch_workspace to change it,' and establishes the operating context that 'every other tool reads and writes only in the active workspace,' so the agent knows why and when to call this.

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 annotations: requires MCP write actions, returns a preview unless confirm:true, changes rebase Share of Voice, and an internal timeline note (labelled by market) is written. It also discloses that a market's list affects only that market's SoV and that the crawler benchmark always reads the project's own list.

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 purpose, then consequences, then parameter semantics in a logical order, and every sentence carries information. However the dense nesting of parentheticals (market/resetMarket and aliases clauses) makes it heavier to parse than necessary for a tool description.

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 10-parameter, nested-object mutation tool with no output schema, the description covers mutation semantics, confirmation flow, market inheritance, and the side effects an agent needs (SoV rebase, timeline note, preview return). Nothing material is missing for correct invocation.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema cannot: the market/resetMarket interaction, the previewToken/confirm pairing, and the project-vs-market list inheritance rule. It clarifies semantics rather than merely restating field docs.

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 pair and resource ('Add or remove competitor brands') and scopes it to a client's AI Visibility, distinguishing it from generic brand management. It never names the sibling manage_rank_competitors, so the AI-visibility-vs-rank-tracking boundary is implied by the scope phrase rather than stated outright.

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 covers when/how to act in nearly every mode: pass market to change one market's list, omit it for the project list, market + resetMarket:true to revert, and confirm:true vs. preview. It also states the effect of each choice (preview names affected markets; reset clears own list/websites/aliases; add/remove/domains/aliases ignored on reset).

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 safety profile (readOnly=false, destructive=false, openWorld=false); the description adds real behavior beyond that: a two-phase preview→confirm flow, the fact that preview reports how many prompts are affected, and that MCP write actions are required. It leaves some tension unaddressed with destructiveHint=false given bulk removal, and says nothing about permissions or reversibility.

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

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

Two tight sentences, front-loaded with the operation and scope, then the argument contract, then the confirm behavior. Every clause carries information; nothing is padding.

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

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

Covers scope, argument contract, and the preview/confirm lifecycle, which is what an agent needs to invoke it correctly, and no output schema is required since the preview result is described. It stops short of mentioning that one of projectId/clientId must be supplied or any error/rate-limit behavior.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds semantics the schema lacks: the mutual-exclusivity constraint between rename and remove (the schema enforces only additionalProperties:false), plus the confirm/previewToken relationship that the schema documents piecemeal.

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 specific verbs (rename, remove), the resource (a tag), and the exact scope (across ALL prompts in a client's project), with the rationale 'bulk tag hygiene'. The 'bulk' framing cleanly separates it from the per-prompt sibling set_prompt_tags.

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 argument-shape guidance ('Provide EITHER rename {from,to} OR remove [tags]') and describes the preview-vs-apply decision via confirm. It does not explicitly name an alternative tool or state when-not to use this one, so it stops short of a 5.

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

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

Annotations only declare readOnlyHint=false/destructiveHint=true/openWorldHint=false; the description goes far beyond that. It discloses that competitors cost nothing, cid-based local matching, subdomain matching rules, the 3-previous-own-site cap and which one stops reading (stoppedReading/readUntil), the eight-week stored-results window, and the preview/confirm/previewToken flow. 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?

The core purpose is front-loaded in the first sentence, but the body is a dense single block with heavy nesting and repeated phrases ('at no cost' appears three times). The complexity of own-site moves justifies length, but the phrasing is not as economical or scannable as it could be.

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 complex write tool with no output schema, the description covers the important edges: preview gating, previous-own-site eviction, subdomain non-matching, and website-change following. It even names result fields (stoppedReading, readUntil) found in the sibling read tool. Only minor gaps remain around returned error/edge cases.

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: isOwn is not just a flag but triggers MOVE semantics with ownUntil/readUntil consequences, and cid is explained as Google's business id used because names are never matched for local results. It adds syntax-adjacent semantics the schema's terse field docs do not convey.

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 opening clause states a precise verb and resource: 'Set the domains whose positions are read from every search of a client,' immediately narrowing scope to own site plus up to ten competitors. This resource is distinct from generic sibling tools like manage_competitors and from the read counterpart get_rank_tracking_setup, which it references. An agent can tell what this tool governs 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?

The description gives clear context for the write path ('Requires MCP write actions; without confirm:true it returns a preview') and explains re-use semantics ('Using a previous own site as the own site again reads it again'). It stops short of an explicit when-to-use-this-vs-alternative routing statement, but the operational conditions are well covered.

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

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

Despite annotations declaring readOnlyHint=false and destructiveHint=false, the description goes far beyond them: it discloses that prompts, answers, daily figures, briefs, timeline notes and signals move and count from the days they ran, that other markets are untouched, that the source project stays inactive and empty, that source-client reports and GEO audits go dark without acceptReportsGoDark, and that it is owners/admins only and requires MCP write actions. The preview/confirmToken gate is also explained. No statement conflicts with the annotations.

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

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

Purpose and the mental model are front-loaded in the first sentence, and essentially every clause carries actionable content given the operation's complexity. It is dense and delivered as a single long paragraph, which makes the later requirements (preview contents, refusals, permissions) harder to scan than a short bulleted breakdown would be.

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?

There is no output schema, yet the description still explains what the preview reports (market, moving counts, warnings, affected source-client reporting) and what the confirm step requires. Permissions, write requirement, refusal conditions, reversibility, and side effects are all covered, so 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%, so the baseline is 3, but the description adds real meaning: it pairs projectId/clientId as "the project that keeps going" and sourceProjectId/sourceClientId as "the one merged in," and documents the otherwise non-obvious fallback where omitting a source makes the tool return candidate projects. It also explains when acceptReportsGoDark is required, though the 15-minute/once previewToken semantics largely duplicate 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 (merge) and resource (another client's AI-visibility project of the same brand as a market) with a concrete worked example: a German project becoming the de-DE market of the main one. It also positions itself against the sibling unmerge_project, which is the inverse, so an agent can distinguish it without opening any schema.

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

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

Gives the selecting condition explicitly (brand tracked as separate projects per country), the alternative behavior when no source is supplied (the answer lists mergeable projects), a refusal list (different brand, same client, multi-market project, already-tracked market, Peec import, running scan), and the undo path via unmerge_project. When-to-use, when-not, and the fallback are all present.

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 annotations only covering safety hints, the description carries the real behavioral burden: cost and pricing (twice the price per page), which account is billed, the daily 20-action cap, one-run-per-client concurrency, the preview-then-confirm state machine, and the 15-minute single-use token. This is unusually rich disclosure that annotations do not provide.

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

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

Single dense paragraph, front-loaded with the core purpose and then costs, permissions, limits, and the preview flow. Every sentence is informative, though the heavy em-dash nesting makes it slightly harder to scan than it could be.

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 paid, capped, stateful action with no output schema, the description covers return behavior adequately: preview until confirm:true, results read later via get_rankings, lastRun shows progress. Cost, permissions, and concurrency are all addressed, leaving no material gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description ties the parameters into the workflow: keywordIds ('only the ones named' / all active), confirm ('returns a preview until called with confirm:true'), and previewToken ('states how many searches... and the most they can cost'). It adds workflow meaning beyond the field descriptions.

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

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

States a specific verb and resource ('Check a client's keywords now instead of waiting for the weekly run') plus scope ('all of them, or only the ones named'). An agent can distinguish this from the read-only get_rankings and from set_rank_schedule 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 the triggering condition (act now vs wait for weekly run), names the complementary read path ('read the result with get_rankings afterwards'), and states prerequisites (write actions AND 'Allow actions that spend AI'). When-to-use and how-to-verify are both explicit.

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

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

Annotations already declare destructiveHint=true and readOnly=false, but the description goes further by spelling out what 'delete' destroys (every position ever measured, changing totals and distribution history), that pause stops 'their cost', and that write actions plus confirm:true are required. This is rich behavioral context well beyond the annotations.

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