Proofsource

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

Annotations only declare the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false); the description goes well beyond them by disclosing async timing (1-2 minutes), the retry semantics that make it idempotent ('picks up the same run, never a second one'), and the return value (brand_id). 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?

Front-loaded with the purpose and outcome, and the polling/retry rule is stated where it matters. It runs long and repeats the schema's link-type list, but each sentence carries usable instruction rather than 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 long-running, open-world tool with no output schema, the description supplies the missing pieces: return value (brand_id), the async wait/poll loop, and the correct next tool. An agent has everything needed to invoke and follow through.

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 are already documented, including the accepted link types and the conditional need for description. The description largely restates the schema's link examples, so it does not add meaning beyond structured data; 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 (start measuring/scanning a brand) and immediately specifies the scope: whether ChatGPT, Perplexity, Claude or Google AI mention it and who they recommend instead. An agent can distinguish this from list_brands or get_visibility 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 names the follow-up tool ('then use get_scan_status'), describes the polling condition ('if it is still running, call again with the same link'), and states when the optional description param is needed ('Only needed when add_brand says it couldn't read the website').

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 real behavioral context beyond annotations: it will be asked on every engine in the plan from the next run, counts toward the plan's question limit, and duplicate calls return the existing question. Annotations already flag idempotentHint=true and destructiveHint=false, so the description usefully confirms and expands that with the practical consequence.

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 tight sentences, front-loaded with the action and effect. Every sentence earns its place: impact, limit, and idempotency behavior.

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

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

For a 4-parameter write tool with no output schema and full schema coverage, the description covers the key concerns: what happens on call, cost implications, and duplicate handling. Could mention confirm_new_engines gating more explicitly, but the schema already handles that.

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

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

Schema coverage is 100% – all four parameters are documented in the schema, including the buyer-phrasing guidance for text and the confirm_new_engines semantics. The description doesn't add syntax or format details beyond the schema, so baseline 3 applies.

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

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

States a specific verb (Adds) and resource (a buyer question to a topic), plus downstream behavior. Distinguishes from siblings like add_brand by naming the object and the product surface (Proofsource) clearly.

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 the effect of adding (asked on every engine from next run) and notes idempotent re-calls. Doesn't name a specific alternative tool to use instead, but the idempotency note and impact statement give strong context for when to use 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?

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 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 establish the safe, read-only, idempotent profile, so the burden is light. The description goes further by enumerating the returned metrics (mention rate, share of voice, average position, citation share, sentiment, period-over-period change) and clarifying the by=question output, which matters given there is no output schema.

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

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

Three dense sentences, front-loaded with the core purpose and then the mode semantics. No filler, though the framing clause in sentence one is slightly 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?

With no output schema, the description correctly carries the return-value burden and does so for both modes. It is complete enough to call the tool correctly, with only minor gaps like pagination or result-size behavior.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning to the enum parameter by differentiating what by=engine versus by=question actually returns. It also confirms the default engines behind the engines filter, which the schema only gestures at.

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 measure (mention rate of the brand) and the exact engines covered, and explains the two output modes, so the resource is unambiguous. It never names or contrasts a sibling, 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?

It gives contextual framing ('when buyers ask about its category') and explains how to choose between by=engine and by=question, which is useful in-tool guidance. However, it never says when this tool should be chosen over sibling analytics tools such as get_competitors or get_citations, leaving cross-tool 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?

The annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so safety behavior is fully covered. The description still adds something the annotations do not: the shape of the result (ids and websites), which matters because there is no output schema. It stops short of pagination, empty-state, or workspace-permission behavior, so it is not 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 short sentences with zero filler. The resource description comes first and the sequencing instruction, the most actionable part, is placed at the end where it lands as the call-to-action.

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, no-output-schema listing tool, the description supplies everything needed: what comes back (ids and websites) and the prerequisite relationship to every sibling tool. There is no annotation or schema information an agent would additionally need before calling 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?

The tool takes zero parameters, so the baseline is 4 under the rubric. The description correctly implies a no-argument call and explains the downstream use of the returned brand_id, which is useful framing but not a parameter semantics gap to fill.

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 brands this Proofsource workspace tracks), the scope (in AI answers), and the payload fields returned (ids and websites). Combined with the list_ verb in the name and the write counterpart add_brand among siblings, an agent can tell exactly what this tool does 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?

It gives explicit ordering guidance: "Call first; every other tool takes a brand_id." This tells the agent both when to use it (before any other tool) and why the alternatives depend on it, which is stronger than a generic when-to-use statement.

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 readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds useful domain context (which AI engines are queried, that topic_ids are returned) but says nothing about pagination, ordering, or what a brand with no topics returns. With annotations carrying the behavioral load, a 3 is right.

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 the resource statement front-loaded and the downstream consumer (create_prompt's topic_id) trailing. 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 one-parameter read tool with no output schema, the description conveys what the tool returns (topics/buyer questions per AI engine) and the key returned field (topic_id). It stops short of describing the shape of each topic entry, but the essentials for correct invocation and follow-up 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% and the single brand_id parameter is fully documented in the schema, including the 'may be omitted for single-brand workspaces' rule. The description adds no parameter-level 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?

States a concrete resource (the topics and buyer questions Proofsource tracks) and the scope (per brand, across four named AI engines), so the agent knows exactly what comes back. It does not explicitly contrast itself with a sibling like create_prompt as an alternative, but the resource is specific enough to be distinguishable.

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 'Gives the topic_id create_prompt needs' supplies a clear when-to-use trigger and chains this tool to the correct next sibling. There are no explicit exclusions or edge conditions, but the workflow context is unambiguous.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false; the description reinforces idempotency with a precise rule ('Calling again with the same fix and description returns the existing record'), which is more specific than the flag alone. It doesn't cover auth requirements or rate limits, so it adds context without fully carrying the behavioral 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?

Two sentences, zero filler, with the core action and the idempotency behavior front-loaded. Every clause (source of IDs, downstream consumer, repeat-call behavior) 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?

No output schema exists, yet the description still tells the agent what a repeat call returns, and it links the write to the verification tool that consumes it. For a 5-param, single-required-param write tool, nothing essential 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 five parameters and the one-of relationship between gap_id and content_draft_id. The description restates that pairing and points at the originating tools but adds no format or constraint detail beyond the schema, matching the baseline 3.

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 pins the identifying keys to their source tools ('gap_id from list_fix_opportunities or a published content_draft_id'). It also distinguishes itself by naming the downstream reader, get_fix_verification, so an agent can place it in the workflow without consulting 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 clear context for when to call it: after a fix ships, using IDs sourced from list_fix_opportunities or a content_draft_id, and explains the payoff is measurement via get_fix_verification. No explicit when-not-to-use or exclusion conditions are given, which keeps it 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 (readOnly, idempotent, non-destructive, not open-world), so the bar is lower. The description adds genuinely useful behavior: no authentication needed, the card is static for Tesla regardless of input, and the brand argument only produces a sign-in prompt. It stops short of describing the card's output structure in detail.

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?

Well front-loaded: the core action and the no-sign-in constraint come first, then the trigger, then the limitation. The final two sentences restate the example-brand constraint already implied earlier, costing a little 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?

For a no-parameter, read-only example tool with no output schema, the description covers what the agent needs: what is returned conceptually, that auth is not required, and that the input brand does not change the payload. Nothing essential is missing, though engine-level detail of the card is only summarized.

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 single 'brand' parameter is already fully documented, including that it is optional and non-determinative. The description's note that the example brand is always shown echoes rather than extends the schema text, so the baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Shows ... a real visibility card for one example brand (Tesla)') and enumerates exactly what the card contains: mention frequency per engine, named competitors, and sample answers. It also implicitly separates itself from the signed-in sibling get_visibility by emphasizing the no-login, example-brand scope.

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 an explicit trigger ('Use it when someone asks whether their brand shows up in AI answers and has not signed in') and states what to do instead for the signed-in case ('to check their own brand they sign in'). The when-to-use condition and the boundary against the real visibility tool are both spelled out.

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