Why Won't AI Mention My Product

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

Annotations already declare readOnlyHint and openWorldHint, and the description is consistent with them. It adds real behavioral context beyond the annotations: RFC 9309 matching semantics, the 17-crawler coverage set, per-crawler verdicts with the deciding rule, and a disclosed daily rate limit for unauthenticated use. Not mentioned: behavior when robots.txt is absent or unreachable.

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

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

One front-loaded sentence carries the core action, resource, scope, and output shape, followed by two short clauses on matching standard and access cost. No filler and no repetition of schema fields verbatim.

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 does the necessary work by specifying what is returned (allow/deny per crawler plus the governing rule). The one gap is the error/edge behavior for sites with no robots.txt or that are unreachable, which matters for a single-fetch open-world tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a level of meaning the schema lacks: it clarifies that 'url' yields a home-page check by default and that 'path' extends the check to a specific page, which is exactly the interaction between the two parameters an agent needs to reason about.

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

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

States a specific verb and resource ('Read a site's robots.txt and report') plus the precise output dimension: per-crawler allow/deny decisions for home page and an optional path, with the deciding rule. This clearly distinguishes it from scan_site and the other scan/issue siblings, which operate on whole-site scans rather than a single robots.txt fetch.

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 by the narrow scope (robots.txt, specified crawlers, single path), and the 'works without an API key (limited per day)' note hints at a cheap pre-flight use. However, it never explicitly says when to prefer this over scan_site or get_scan, nor states exclusions or prerequisites such as the site being publicly reachable.

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, so safety is covered; the description adds meaningful behavior beyond that by disclosing the bounded blocking wait (up to 25s) for running scans and by previewing the returned payload despite there being no output schema. It stops short of covering output format details or rate limits, keeping it a solid but not exhaustive 4.

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 purpose and followed by the operational tip; no filler. The enumerated return list is dense but earns its space given the absence of an output schema.

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

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

For a two-parameter read tool with full schema coverage and a readOnlyHint, the description supplies what the structured data cannot: expected return content and the bounded-wait polling pattern. Nothing essential to calling it correctly is missing, though a note on whether waiting is required versus optional polling would close the last gap.

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

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

Schema coverage is 100%, so both parameters (including the 0–25 range and default of 0 for wait_seconds, and the provenance of scan_id) are already documented in structured fields. The description restates the wait cap and the scan-summary fields but adds no syntax or edge-case meaning beyond the schema, so the baseline 3 applies.

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

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

The description opens with a specific verb+resource pairing — status/progress/summary of a scan — and enumerates the concrete data it returns (score and band, category scores, Domain Rating, top issues), so an agent knows exactly what this call yields. It does not explicitly contrast itself with scan_site or list_scans, though the scan_id schema note points back to them.

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 second sentence gives actionable polling guidance: set wait_seconds (max 25) to block until a running scan finishes, which tells the agent how to handle in-progress scans. However, it never states when to reach for this tool versus list_scans (enumerate scans) or scan_site (start one); that routing is only implied by the schema hint on scan_id.

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?

readOnlyHint=true already covers the safety profile, and the description usefully adds ordering and the shape of returned content (details plus example URLs). However, "All issues" conflicts with the limit parameter's default of 25, so the description overstates completeness and hides truncation behavior, which is a real gap for an agent reasoning about coverage.

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 sentence with zero filler, front-loaded on what is returned before moving to ordering and then filtering. Every clause carries information an agent needs.

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

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

With four parameters, no output schema, and only a readOnlyHint annotation, the description should do more: it never explains truncation/pagination (limit), what an empty result means, or the required scan_id's provenance. It conveys return shape and ordering but leaves the agent guessing about result coverage.

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 75% and the schema already documents category examples, the severity enum, and limit's default, so the baseline applies. The description's "filter by minimum severity or category" restates rather than extends the schema, and the required scan_id is undocumented in both places.

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 sentence names a concrete resource (issues) scoped to a specific origin (a completed scan) and adds ordering and payload hints ("most severe first, with details and example URLs"). It is unambiguously different from get_scan/list_scans/scan_site by resource, but never explicitly routes the agent away from those 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?

"Completed scan" implies a precondition (the scan must have finished) and the last clause names two supported filters, so usage is implied. There is no explicit when-to-use versus get_scan, no guidance for an in-progress scan, and no statement of the alternative when the agent wants raw scan metadata.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds genuine context beyond annotations: results are scoped to the API key owner and returned newest-first with score and status. It says nothing about pagination behavior, result caps, or what an empty result means, so it is useful but not rich.

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

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

A single front-loaded clause with zero padding: scope, ordering, and payload are all stated up front. It is a sentence fragment, which is efficient but slightly telegraphic.

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 two-optional-parameter read tool with annotations covering safety and a fully described schema, this is close to sufficient, and it helpfully states what fields come back even without an output schema. Minor gaps remain around pagination and result limits, which are only inferable from the schema.

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

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

Schema description coverage is 100%, so limit (default 10, max 20) and domain filtering are already documented in the schema. The description adds no filtering or limit semantics 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 resource (scans) and its scope (the API key owner's), plus ordering and returned fields, so an agent can tell it apart from get_scan (single scan) and list_issues. It never states the verb explicitly, relying on the name/title to convey 'list', and it does not name siblings directly.

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 statement of when to use this versus get_scan, list_issues, or scan_site, and no prerequisites or exclusions. The only hint is the word 'recent', which implies a discovery/browse use case but leaves the agent to infer 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 only say it's a non-read-only, non-idempotent, open-world call; the description adds the material facts an agent needs: it burns the API key owner's plan quota, it makes live outbound requests impersonating six crawlers, and it is asynchronous (returns scan_id rather than results). That is real disclosure beyond the structured fields.

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

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

Two sentences, both load-bearing: the first front-loads the action and its scope, the second handles return value, cost, and the next call. No filler or restatement of 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 an async kick-off tool with no output schema, the description supplies the missing return contract (scan_id) and the follow-up call, plus the quota side effect. Nothing an agent needs in order to invoke it correctly is absent.

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 url parameter is already documented with a format example. The description adds only indirect semantics — 'each page is requested separately' hints the input is a site root whose pages get enumerated — so it neither compensates for nor extends the schema meaningfully. 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 ('Start a full scan of a website') and then spells out what the scan actually does — multi-bot fetches, rendered comparison, six SEO/AEO/GEO categories, Domain Rating. That level of specificity clearly separates it from get_scan (retrieval) and list_scans (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?

Explicitly defines the workflow: 'Returns a scan_id; then call get_scan with wait_seconds' — an agent knows this is the entry point and what to call next. It also signals cost via 'Uses the API key owner's plan quota', though it doesn't state when NOT to scan (e.g. dedupe against an existing in-flight scan) or any rate limit.

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