MentionedOn Discovery Evidence Tools

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is known. The description still adds real value by enumerating what the tool will NOT do (no fetch, no scan, no persistence, no verification), which is behavioral context beyond the structured hints.

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

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

Two sentences, zero filler, purpose front-loaded and the boundary condition immediately after. 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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The description adequately frames scope and input origin for a 3-param, stateless scoring tool, though a hint about how to interpret an overall score would round it out.

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 each nested field is documented in the schema, so the description carries no additional burden. The phrase 'caller-supplied website and business discovery signals' loosely maps to websiteUrl/signals but adds no syntax or format detail. 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 ('Score caller-supplied website and business discovery signals'), which is clear and distinct from building an action plan or summarizing scan evidence. It does not name its siblings explicitly, so differentiation is inferred rather than stated.

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 negative list ('does not fetch the website, run an AI scan, persist data, or verify inclusion') effectively tells the caller when this tool applies: only when signals are already in hand. This routes away from scan/fetch tools but stops short of explicitly naming the alternatives.

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 partly covered. The description still adds domain-specific context beyond the annotations: it does not edit a website, contact third parties, persist data, or promise rankings/mentions — the last point being genuinely new behavioral information about the absence of outcome guarantees.

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, purpose front-loaded, no filler. The negative-scope sentence is dense but each clause carries distinct information. Slightly more structured routing guidance could shorten the inference load, but nothing is wasted.

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

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

An output schema exists, so return values need not be described, and the read-only/non-persistent nature is covered. For a 4-required-parameter tool this is nearly complete; the remaining gap is explicit routing relative to the two sibling tools.

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 75%, so the schema does most of the work (goal tie-breaking, status semantics, evidence length limit). The description only alludes to the findings array via "caller-supplied findings" and adds no syntax or format detail beyond what the schema already provides, so 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 ("prioritize fixes") and names the mechanism ("deterministic rubric") plus the input source ("caller-supplied findings"). This distinguishes it from a general analyzer, but it never names the siblings analyze_discovery_readiness or summarize_scan_evidence, so an agent must infer the boundary rather than read it.

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 phrase "from caller-supplied findings" implies this is a downstream step that consumes output from an earlier scan/analysis tool, giving weak implied routing. There is no explicit statement of when to choose this over analyze_discovery_readiness or summarize_scan_evidence, and no when-not conditions.

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

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

The annotations only carry hint flags, so the description carries the behavioral burden and does well: it discloses no model spend, no external publication, no messages sent, and a revision-preservation (concurrency) constraint, which is real value beyond the annotations. It does not say what happens on a stale revision or to an existing draft, so it falls 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, front-loaded with the core action followed by constraints; there is no filler. Slightly dense given the compound first sentence, but every 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?

An output schema exists, so return values need not be described, and the safety/scope profile is well covered for a write tool. What is missing is failure behavior for a mismatched revision and whether an existing draft is overwritten, which matters for a non-idempotent mutation.

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 40% (only revision and businessId are documented; the 11 nested facts fields and businessType are not), so the description is expected to compensate. It clarifies that `facts` must be user-confirmed and not invented, which is meaningful, but it does not explain the nested fact fields or the businessType enum choices.

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: 'Generate and save reviewable business schema, website copy and a business-profile description.' This clearly separates it from the read-side get_website_fixes and the verify_website_fixes siblings, though it never names them 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?

'Inspect first' implies a sequencing prerequisite (presumably inspect_business_website) and 'facts the user explicitly confirms' sets an input precondition. However, no sibling is named and there is no explicit when-to-use vs when-to-use-alternative routing, 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?

While annotations cover safety (`readOnlyHint: true`), the description adds vital context regarding the nature of the operation, specifying that it reads 'saved' snapshots rather than generating live data. This informs the agent about the temporal nature of the 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 description is dense, but every clause contributes to a functional definition. It is not overly verbose; it front-loads the key data points and behavioral constraints efficiently.

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

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

Given that the tool performs a complex analysis of historical captures and comparisons, the description is highly complete. It covers the data sources, the comparison rules, and the operational limitations, leaving no ambiguity about its functionality.

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 description adds meaningful context to the 'limit' parameter by specifying that it controls the retrieval of 'prior snapshots,' which elevates the description beyond the basic schema definition. The definition for 'businessId' is also helpful.

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 is extremely specific, focusing on reading 'latest saved AI capture, competitors, source links and up to 30 prior snapshots.' It successfully differentiates this reporting function by stating it 'does not query models or establish current consumer-app inclusion'.

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 provides explicit instructions on usage constraints, mandating that 'compare scores only when saved model, prompt and capture recipes match and both captures are complete.' It also provides a clear negative constraint, detailing what the tool does not do.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The added statement 'No website is fetched or changed' largely restates those hints rather than disclosing new traits such as retrieval scope, size, or freshness characteristics.

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 zero filler. The content enumeration comes first and the scope-limiting guarantee ('No website is fetched or changed') closes the sentence, so the most important disambiguation is front-loaded and nothing is wasted.

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

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

With an output schema present, the description need not explain return values, and annotations cover the safety profile, so the core is complete for this simple one-parameter read tool. It is only slightly short of full completeness because it omits any routing signal toward the sibling tools that write or verify the same fixes.

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 parameter with 100% schema description coverage; the schema itself explains businessId and points to list_monitored_businesses as its source. The description contributes no additional meaning about the parameter, which is the expected baseline when the schema does the heavy lifting.

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

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

The description uses a specific verb ('Read') and enumerates exactly what artifact is returned — current revision, source observations, confirmed facts, proposed schema/copy, installation checks — for an owned business. It distinguishes itself from website-touching siblings by stating 'No website is fetched or changed', though it never names the closest alternatives (draft_website_fixes, verify_website_fixes) 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?

The clause 'No website is fetched or changed' implies this is the read path for previously saved work, which signals usage context. However, it gives no explicit when-to-use, no condition distinguishing it from draft_website_fixes or verify_website_fixes, and no prerequisites beyond what the schema supplies.

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 say readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds what those hints cannot: the tool makes bounded public HTML requests (open-world network scope), requires a paid/trial slot plus explicit authorization, writes candidate facts with source receipts, and preserves existing draft content. It also explicitly disclaims AI scanning and publishing, so no contradiction 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?

Five short sentences, each carrying a distinct payload (action, precondition, revision requirement, draft-preservation rule, scope exclusions), with the core action front-loaded. Dense but not padded; a little more structural grouping of preconditions would earn 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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. The description supplies the remaining operational context an agent needs: slot requirement, authorization, revision passing, and draft-preservation behavior. It could be more explicit about what happens on a stale revision, but coverage is strong overall.

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 67%; revision and businessId are documented in the schema, and authorizationAcknowledged carries no description beyond const true. The description reinforces two of these ('Pass the exact current revision', 'explicit authorization'), which clarifies intent but adds little syntax or format meaning beyond the schema. Baseline 3 for moderate coverage.

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: fetch the saved business website, run bounded public HTML requests, and save candidate facts with source receipts. It also carves out scope against siblings by declaring 'Does not run AI scans or publish anything', which separates it from analyze_discovery_readiness and draft_website_fixes. The differentiation is generic rather than naming a specific sibling, 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?

Gives real preconditions (paid or trial monitoring slot, explicit authorization) and sequencing advice ('start a new inspection only before confirming facts'). It does not name a specific alternative tool or state when another tool should be preferred, so it is clear context without 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?

Adds real information beyond the annotations: it discloses that an empty account gets a setup link and that no scan, subscription, or charge is triggered — meaningful for an agent worried about side effects. The read-only/idempotent safety profile is already covered by annotations, so this is additive rather than redundant.

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?

Four short sentences, each carrying a distinct fact: what is listed, when to call it, the empty-account setup link, and the absence of cost. Purpose is front-loaded with no filler.

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

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

With an output schema describing returns, rich annotations, and no parameters, the description supplies everything still needed: entry-point guidance, empty-account behavior, and cost/scan reassurance.

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 schema baseline is 4 and there is nothing further a description could clarify about inputs.

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 (businesses owned by the connected MentionedOn account) plus what metadata comes back (monitoring/setup status). This is clearly a read-oriented inventory tool, distinguishable from the analysis/report siblings such as get_visibility_report or analyze_discovery_readiness.

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?

"Start here when the user asks how their business appears in AI answers" gives an explicit entry-point condition. It does not enumerate a when-not-to-use case or name a sibling alternative, so it stops 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 (readOnly, non-destructive, openWorldHint=false), yet the description adds substantive behavioral disclosure beyond them: no provider calls, no URL fetching, no persistence, and no claim to establish current inclusion beyond the supplied observations. The last point is genuinely important, since it warns the agent not to treat the output as a live visibility measurement.

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, with the positive statement of function front-loaded and the constraints following. The disclaimer sentence is long but every clause does work by closing off a plausible agent misreading. Minor cost: the negative framing dominates the description's 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?

An output schema exists, so return-value explanation is unnecessary. The description correctly establishes the input source and boundaries, but omits how non-completed observations (the error/skipped variant in the schema) affect the computed rates, and does not indicate the scope or time basis of the calculation. Adequate but with a real gap for a tool whose only job is deriving rates.

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 50%, so the schema partially documents the observation fields (sourceLabel, surfaceType, observedAt, businessCitationUrls). The description links the output to two of those concepts ('mention' and 'business-citation' rates), adding some interpretive value, but says nothing about businessName or how the completed vs. error/skipped observation variants are treated. Roughly baseline for this coverage level.

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

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

The first sentence states a specific verb and resource: 'Calculate mention and business-citation rates from caller-supplied captures.' That is concrete enough to distinguish it from siblings like build_visibility_action_plan, which build plans rather than compute rates. It does not, however, explicitly name or contrast itself against either sibling.

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 context is implied rather than stated: 'caller-supplied captures' tells the agent this tool consumes data the agent already holds, and the exclusions ('does not call AI providers, fetch URLs') rule out the expectation of live scanning. But there is no explicit when-to-use statement and no routing guidance relative to analyze_discovery_readiness or build_visibility_action_plan.

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 declare readOnlyHint=false / openWorldHint=true / idempotentHint=false, and the description is consistent, adding real behavior the annotations don't carry: it persists dated check records, requires authorization and an entitled slot, and explicitly scopes the result ('installation checks do not prove a visibility improvement'). It stops short of warning that repeated runs create duplicate dated records despite the non-idempotent hint.

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?

Four short sentences, heavily front-loaded: the action first, then the persistence behavior, then prerequisites, then the caveat. Each sentence carries information, with only the slightly redundant 'same owned business website' phrasing costing anything.

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

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

An output schema exists, so return values need no explanation, and the description supplies the prerequisites, mutation semantics, and interpretive caveat an agent needs to call it correctly. The main residual gap is the under-documented parameters (three of four lack any description).

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

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

With only 25% schema description coverage, the description must compensate and partly does: 'exact artifact revision' anchors the revision integer, 'page on the same owned business website' anchors url, and 'Requires authorization' anchors authorizationAcknowledged. It still omits the url length bound, the revision > 0 constraint, and the boolean-const nature of the acknowledgement, so coverage remains incomplete.

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 specific verb pair (compare, save) and a concrete resource (saved reviewed schema/text vs. a page on the owned business website), plus the recorded output (dated found/not-found/unknown checks against the artifact revision). It is clearly distinct from sibling tools like draft_website_fixes or get_website_fixes, though it never names a sibling to make the boundary explicit.

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 two prerequisites (authorization and an entitled monitoring slot) and a scope caveat ('do not prove a visibility improvement'), which implies post-installation use. But it never explicitly says when to prefer this over get_website_fixes or inspect_business_website, so the routing guidance is only implied.

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