Proofsource

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

Goes well beyond the annotations: it discloses the 1-2 minute site-reading latency and explains idempotency concretely ('call again with the same link and it picks up the same run, never a second one'), which makes idempotentHint=true actionable. It also states the return value (brand_id) and that the tool itself reads an external site, consistent with openWorldHint=true and readOnlyHint=false.

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

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

Purpose is front-loaded in the first sentence and each subsequent sentence adds operational value (accepted link forms, execution time, retry semantics, next step). It is dense but slightly long, with the parenthetical link list and retry clause adding bulk that could be tightened.

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 async, side-effecting creation tool with no output schema, it covers everything an agent needs: what starts, how long it takes, how to poll without duplicating a run, what ID comes back, and which sibling to call next.

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 are already documented with examples and constraints. The description reinforces the link variants and the 'description is only a fallback' condition, but adds no meaning the schema lacks, and it never mentions the locations parameter or its per-location splitting behavior.

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 measuring a brand') and immediately makes the output concrete: whether ChatGPT, Perplexity, Claude or Google AI mention it and who is recommended instead. It also distinguishes itself from siblings by naming get_scan_status as the follow-up and by accepting website or social/app-store links, so an agent can tell what this does versus list_brands or get_scan_status.

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

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

Gives a clear trigger (you want to start tracking a brand) and explicitly routes the agent afterward to get_scan_status, plus tells it how to resume an in-flight run. It does not state when not to use it (e.g., brand already exists — presumably list_brands), so it falls short of full alternatives coverage.

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=false and idempotentHint=true, but the description adds substantive behavior: it consumes the plan's question limit, takes effect only from the next run, and is deduped by text so a repeat call returns the existing question rather than creating a duplicate. That is exactly the kind of consequence-level detail 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?

Three short sentences, front-loaded with what the tool does, then the quota cost, then the idempotency guarantee. No filler and no redundancy with the title.

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 4-param create tool with no output schema, the description covers purpose, quota impact, dedupe behavior and run timing. It stops short of describing the shape of the returned question object, but the idempotency sentence gives enough of the return behavior for correct invocation.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema, including the confirm_new_engines safety flag and the omitted-engines default. The description adds no parameter-level detail 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?

The description gives a precise verb+resource+effect: it adds a buyer question to a topic and schedules it to be asked on every engine from the next run. That is far more than a restatement of the name/title. It does not explicitly contrast with a sibling (the closest, add_brand, is unrelated), 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?

Use is implied (this is how you track a buyer question) and the topic_id description points to list_topics, but the description never says when to use this versus another tool or states prerequisites. It does imply the question consumes a plan quota, which is useful context but not routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is fully covered. The description adds the trailing-window scoping notion but nothing further — no pagination, latency, or result-size behavior. This matches the calibration bar for a read tool whose annotations carry the safety burden.

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

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

A single front-loaded sentence with no filler, and because no output schema exists, enumerating the returned categories is legitimate content rather than padding. It is dense but each clause carries 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?

With no output schema, the description usefully enumerates what comes back, and annotations cover the safety profile. It still omits when to call this rather than get_visibility, and gives no hint about the shape or granularity of the returned change objects.

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 brand_id and window_days semantics are already fully documented, including the default of 30 days and the single-brand omission rule. The description's 'over the window' phrasing adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

The description states a specific resource — the change/delta report for AI visibility over a trailing window — and enumerates what it covers (mention-rate trend, answer churn, competitor site changes, new category pages). It is distinguishable from the static snapshot implied by get_visibility. However, there is no governing verb, so the agent must infer 'retrieve changes' from the enumeration.

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 is given, no exclusions, and no comparison to get_visibility (the obvious alternative for current-state data). The agent must guess whether this is a diff versus a snapshot based purely on the tool name.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the ranking semantics (share of citations vs. number of answers citing) and that the brand's own site is included, which is useful output context. It says nothing about cost, latency, or how the reply is structured, so it is solid-but-not-rich against the annotation baseline.

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 that leads with the ranking subject and ends with the brand's own position. It is dense but every clause carries information; no filler or repetition.

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

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

There is no output schema, so the description must carry the return-value burden, and it does explain what the two rankings represent and that the brand's own site rank is included. It leaves gaps around reply structure and engine breakdown that the agent must learn from the schema or the response itself.

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 schema already documents limit, engines, brand_id, and window_days, including defaults and the counted_engines behavior. The description adds no parameter meaning 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 names the concrete resource (websites cited by AI answers for the brand's buyer questions) and the exact shape of what comes back: two rankings plus the brand's own site position. It is far more specific than the tool name alone. It does not, however, contrast itself with close siblings like get_visibility or get_competitors, so the agent must 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?

There is no when-to-use or when-not-to-use guidance, no prerequisites, and no named alternative. An agent deciding between this, get_visibility, and get_competitors gets no routing help at all.

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, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely useful behavioral content beyond that: the return is scoped per engine, includes each competitor's share of voice against the brand, and includes the delta over the window. No auth or rate-limit notes, but for a read-only analytics tool this is solid.

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

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

A single dense sentence with no filler, and the core resource (competitors named in AI answers) is front-loaded. It is slightly run-on, packing scope, per-engine grain, metric, and time comparison into one clause chain, but every 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?

With no output schema, the description carries the return-value burden and does so: competitor identity, per-engine grain, share of voice, and change over window. Combined with annotations covering the safety profile and a 100%-documented schema, an agent has what it needs to call this correctly; only the sibling-routing guidance 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 all three parameters (engines, brand_id, window_days) are already documented in the schema, including defaults and the engines example list. The description adds no parameter-level detail beyond that, 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 states a specific verb+resource: it returns the competitors named in AI answers to the brand's buyer questions, broken down per engine with share-of-voice and change over the window. That is far more precise than a restatement of the name. It does not explicitly distinguish itself from sibling analytics tools like get_visibility or get_citations, 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?

There is no when-to-use or when-not-to-use guidance and no named alternative. An agent must infer from the name alone that this is the competitive-share tool versus get_visibility (own-brand visibility) or get_citations (source attribution). Purely descriptive, no routing help.

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 safety (readOnly, idempotent, non-destructive, closed-world), and the description adds real value on top: the verdict vocabulary (moved / within_noise / awaiting_samples), the exclusion of non-fix rows, and the auto_detected provenance marker. It does not say how long 'awaiting_samples' persists or whether results are recomputed on each call, which keeps 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?

Two sentences, no filler, and the inclusion/exclusion and verdict semantics are packed efficiently. The opening clause is dense and the verdict list arrives late, so front-loading could be slightly better.

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 describing the return and does so at a high level: per-fix before/after mention rate plus verdict labels. It remains silent on result freshness, pagination beyond the schema's limit, and empty-result behavior, so it is strong but not exhaustive.

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 limit, brand_id, and fix_event_id are already fully documented in the schema. The description only reinforces brand scoping and the single-fix case without adding format or edge-case detail beyond the schema, which is the baseline 3 situation.

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 verifiable resource and what it returns: every fix marked shipped for a brand, with mention rate before/after and a verdict. It is easily separable from siblings like get_visibility and list_fix_opportunities because it is scoped to shipped fixes and their measured outcome.

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: an agent can infer this is the post-shipment follow-up to mark_fix_shipped, but neither that sibling nor any alternative is named, and no when-not condition is given. The exclusion mentioned ('Not a fix' rows) concerns result content, not tool selection.

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

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

Annotations already establish a safe read-only, idempotent operation, yet the description adds substantial behavioral texture on top: the fixed verification cadence (day 28, then 45/60/75, final at 90), the caveat that 'a horizon appears only once it has been measured,' the fact that before_window appears only on the first page, and the 90-day-per-call ceiling. These are non-obvious traits an agent could not 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?

The opening clause is well front-loaded, but the remainder is a single run-on sentence of roughly 100 words that chains the stage list, the verification cadence, the metric inventory and the before_window rule together. All the content is relevant, yet the lack of sentence breaks or ordering makes it harder to parse than its density warrants.

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 describing the return payload, and it does so: stage progression, per-horizon sample sizes, citation/mention/AI-referral movement, and the before_window object. What it omits is the concrete shape of an individual step record, leaving the agent to infer fields from the prose.

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 baseline would be 3. The description earns more by clarifying runtime semantics the schema does not: the 90-day maximum window expressed as the 'last N days is since = today minus N-1' arithmetic, and that paging continues via next_cursor rather than offset. It does not, however, explain how the stages filter interacts with before_window.

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 resource — the brand's full loop timeline from buyer question tracked through gap found, draft created, published, fix shipped, page changed and verified — and states sort order (oldest first). An agent gets a clear picture of what is returned. It stops short of naming the sibling it differs from, notably get_fix_verification and get_changes, which cover adjacent territory.

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 90-day window rule and the since/until arithmetic ('since = today minus N-1, today counted'), which tells the agent how to scope a call. However, there is no explicit statement of when to reach for this tool versus get_fix_verification or get_changes, and the only routing hint is the incidental 'brand_id from list_brands.'

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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: it returns the newest *finished* report's own unlisted link, and reports are built automatically only after a brand's first scan. It does not cover what happens when no finished report exists.

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 outcome (the link) before the explanatory details. No filler and nothing repeated from the name or title.

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 does so by describing the link and its content plus the precondition (a finished report exists after the first scan). The one gap is the behavior when no finished report is available.

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

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

Schema coverage is 100% and there is a single optional parameter fully documented in the schema, so the schema does the heavy lifting. The description adds no syntax or format detail about brand_id. 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 and resource (returns the shareable link to the brand's AI visibility report) and enumerates its contents (mention frequency, competitors, cited sources). It is distinguishable from siblings like get_visibility and get_citations by promising a link rather than raw data, though it does not name those siblings 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?

"To share with a team or client" implies the use case, but there is no explicit when-to-use guidance, no when-not, and no alternative tool named for agents that want the underlying metrics instead of a shareable link.

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 read-only, idempotent, non-destructive behavior, so the description doesn't need to restate safety. It does add useful behavioral substance by describing the shape of progress reporting (stage, counts, per-engine, ETA). It omits any polling/refresh guidance, which is the main remaining behavioral gap for a status 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?

Two sentences, no filler. The main clause front-loads the resource, the middle clause lists return content, and the final sentence carries the routing instruction.

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 convey what comes back, and it does so at a functional level: stage, counts in/expected, per-engine breakdown, and completion estimate. It stops short of naming concrete stage values or a finish-time format, but an agent has enough 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?

Schema coverage is 100% and the single brand_id parameter is fully documented there, including the omission case for single-brand workspaces. The description adds nothing about the parameter, 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 (progress of a brand's first scan) and enumerates exactly what the caller learns: stage, answers in vs. expected, per engine, and finish estimate. It also scopes itself to the post-add_brand scan, which separates it from get_visibility and the other read 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?

Explicitly places the tool in a workflow ("a brand's first scan after add_brand") and hands off the next step with a condition: "Once complete, use get_visibility for the results." Both when-to-use and the alternative are stated rather than 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?

Annotations already declare readOnly/idempotent/non-destructive, so the description is free to add value, and it does: change-from-previous-period comparisons, an extra 'locations' block for multi-location brands, competitor ordering 'weakest first', and the counted_engines note. That said, pagination/response limits and empty-state behavior are unaddressed.

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 question and then the two modes, with no filler. The final sentence is long and slightly run-on, but every clause conveys distinct output structure.

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 four optional parameters, the description carries the return-shape burden and does so by describing what each by mode yields plus the location block. Minor gaps remain (what an engine with no data returns, how window_days interacts with the 'change' comparison), but the essentials are present.

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 every parameter including the engine defaults and brand_id omission rule. The description's mention of the by default and engine list largely restates the schema rather than adding new syntax or constraints, 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 resource (brand mention visibility across named AI engines) and enumerates the exact metrics returned, so the agent knows this is the analytics read for AI-answer mentions. It does not explicitly distinguish itself from close siblings like get_citations or get_competitors, which leaves some ambiguity about which tool answers which question.

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 by=engine/by=question split gives clear mode selection with a stated default, which is real usage guidance. However, there is no guidance on when to call this instead of get_citations, get_competitors, or get_changes, and no prerequisites or exclusions are mentioned.

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, idempotentHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds the non-obvious sequencing behavior (prerequisite entry point for the workspace), which is genuine behavioral context. It doesn't mention pagination or what happens on an empty workspace, keeping it short of 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?

Two sentences, roughly 20 words, zero filler. The resource definition leads and the call-ordering instruction follows immediately.

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-param listing with no output schema, the description supplies the essential return fields (ids, websites) and the call-order contract. It stops short of noting result size, ordering, or the empty-workspace case, which would be the last piece of context an agent could want.

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, which is the baseline-4 case, and the schema is a closed empty object. The description adds only the identity of the returned fields (ids and websites), which is return-value information rather than parameter semantics.

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

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

States a specific verb (list) and resource (the brands this workspace tracks in AI answers), plus the return shape (ids and websites). The clause 'every other tool takes a brand_id' separates it from all 12 siblings without needing a schema read.

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

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

Explicitly prescribes the call order: 'Call first; every other tool takes a brand_id.' This is a when-to-use rule with an implied when-not (not needed once you already hold a brand_id), plus the dependency on downstream tools.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so safety is covered. The description adds genuine behavioral context beyond that: every gap is returned with its evidence and a suggested fix, and the returned gap_id is the input mark_fix_shipped expects — useful workflow coupling the annotations do not express.

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 with no filler. The core resource definition is front-loaded and the workflow hook (gap_id → mark_fix_shipped) is placed last as supporting detail.

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

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

There is no output schema, but the description compensates by describing the shape of each returned item (gap, evidence, suggested fix, gap_id). Combined with fully documented parameters, an agent has enough to invoke and interpret it, though pagination or ordering behavior is unstated.

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 both parameters (brand_id, include_closed) are already documented in the schema, including the single-brand omission case and the default for include_closed. The description adds nothing further about parameters, 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 names the specific resource returned — the gaps that prevent AI engines from citing/recommending the brand — plus what each entry contains (evidence and suggested fix). It differentiates from siblings by tying itself to mark_fix_shipped via gap_id, so an agent can place it in the workflow without opening another schema.

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

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

Usage is implied: call this when you want remediation targets for AI visibility, and the mention of gap_id feeding mark_fix_shipped clarifies its downstream position. However, it never states when to prefer this over adjacent tools like get_visibility, get_competitors, or get_changes, and gives no exclusions.

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 the full safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the behavioral burden is light. The description adds the useful context that this is a scoped, workspace-and-brand-specific read across four AI platforms, but says nothing about result size, 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?

Two compact sentences with no filler; the resource definition comes first and the downstream create_prompt linkage is front-loaded in the second clause. Every phrase earns its place.

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

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

For a simple one-parameter read tool with annotations covering safety and no output schema, the description is nearly sufficient. It explains what is returned conceptually, though it omits return shape details such as pagination or whether topic_id values map one-to-one with prompts.

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 brand_id parameter is fully documented in the schema, including the fallback behavior for single-brand workspaces. The description adds no parameter detail of its own, 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 names the specific resource — the topics and buyer questions tracked for a brand — and scopes it to the workspace, with the four AI engines listed as the query targets. It also routes to create_prompt via topic_id, which helps distinguish it from other list-style siblings, though it doesn't directly contrast with list_brands.

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 note that it 'gives the topic_id create_prompt needs' tells the agent this is the lookup step before create_prompt. There is no explicit when-not guidance or mention of conditions like empty results or when another listing tool would be preferable.

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 non-read-only, idempotent, non-destructive, closed-world. The description adds real context beyond them: the idempotent repeat call returns the existing record, and the record feeds mention-rate verification downstream. It omits the refusal path for drafts with unfilled [INSERT] gaps, but that is covered in the schema parameter description.

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, no filler, and the core action plus its downstream purpose are front-loaded before the idempotency note. Every clause earns its place.

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

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

For a 6-parameter mutation with only one required field and no output schema, the description covers purpose, input sourcing, idempotency, and the verification loop. It could mention what the recorded result looks like or the unfilled-gaps refusal, but the schema fills those gaps.

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

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

Schema coverage is 100%, so the baseline is 3, and the description goes beyond it by naming the sourcing tool for gap_id and qualifying content_draft_id as a published draft. It does not add format or default details for shipped_at/brand_id, which the schema already handles.

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 ('Records that a fix shipped') and immediately scopes it to the two valid ID sources (gap_id from list_fix_opportunities, or a published content_draft_id). It also names the downstream consumer, get_fix_verification, so the agent understands what this write is for and can distinguish it from sibling list/get 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?

Clearly says which inputs to use and where they come from ('against a gap_id from list_fix_opportunities or a published content_draft_id'), and states the repeat-call behavior. It gives strong positive guidance but no explicit when-not-to-use rule or prerequisite conditions (e.g., that the fix must actually be shipped before recording).

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 safety (readOnly, idempotent, non-destructive, closed-world), and the description adds the genuinely non-obvious behavior: no sign-in required, and the card ALWAYS shows the example brand regardless of what is passed in. That 'input does not change output brand' trait is exactly the kind of context an agent cannot get from the schema or annotations.

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

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

Front-loaded with what the tool shows, then the usage condition, then the fixed-brand caveat — a sensible order with no filler sentences. It is slightly repetitive, restating the sign-in/own-brand point twice in the final sentence, which is the only thing keeping 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 no output schema, the description carries the return-value burden and does so by listing the card's contents (mention rate per engine, competitor names, sample answers). For a zero-required-parameter, read-only demo tool with full annotation coverage, nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100% and the single optional 'brand' parameter is already documented, so the baseline is 3. The description goes slightly beyond by confirming the example card is returned either way and that the named brand is only echoed with a sign-in note, which clarifies why the parameter exists at all.

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 concrete verb and resource — shows a real AI visibility card for one fixed example brand (Tesla), sourced from ChatGPT, Perplexity, Claude and Google AI Overviews. It also enumerates what the card contains (mention frequency per engine, named competitors, sample answers), which clearly separates it from siblings like get_visibility or get_competitors that serve a signed-in user's own brand.

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 trigger ('when someone asks whether their brand shows up in AI answers and has not signed in') and the exclusion ('to check their own brand they sign in'), implicitly routing to the authenticated sibling tools. Nothing about when to pick this over get_visibility 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.