Agent Ready

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, so the description need not repeat that. The description adds useful behavioral context: results are Schema.org-typed, mode 'summarize' adds an extractive summary, and itemType narrows the corpus. No contradictions with 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?

The description is concise, consisting of three sentences that front-load the core purpose, then add return type and optional parameter behavior. Every sentence earns its place, with no redundancy.

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

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

With an output schema present, the description does not need to detail return values. It fully covers what content is searched, the optional narrowing and summarization modes, and the result type. It is complete for a search tool, though it omits any mention of pagination or result limits, which is slightly expected for a search operation.

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% with each parameter well-described, so the baseline is 3. The description adds slight extra meaning by explaining itemType narrows to a corpus type and mode 'summarize' adds a summary, but these largely echo the schema and no new syntax or examples are provided.

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

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

The description clearly states the tool performs natural-language search over Agent Ready's own content, listing specific corpora (methodology, check registry, specs, content library). It also mentions the return type (Schema.org-typed objects), making the purpose specific and distinct from sibling scan 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?

The description provides clear context on what content is searched and that mode/itemType can adjust the query, implying when to use it. However, it does not explicitly mention when not to use it or provide alternatives like the sibling tools get_scan and scan_site.

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, and non-destructive hints. The description adds valuable behavioral context beyond annotations: it specifies that scans can be 'completed or in-progress' and that ownership is restricted to the authenticated user. This provides meaningful transparency without contradicting any annotation.

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 two sentences, directly addresses the tool's function and a key security constraint, and avoids any filler or redundant phrasing. Every word contributes meaning.

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

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

For a simple fetch-by-id tool, the description is complete: it states what is fetched, the allowed states, and the ownership restriction. The presence of an output schema means return format doesn't need to be described. The tool is fully specified given its simplicity and rich annotations.

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 input schema provides 100% coverage for the single 'id' parameter, including a detailed description linking it to scan_site and the share token URL. The tool description itself does not add additional parameter semantics, so the baseline of 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 uses a specific verb ('fetches') and a clear resource ('scan by its id'), making the tool's purpose immediately obvious. It also adds an ownership scope ('Only scans owned by the authenticated API key's user are returned'), which further distinguishes it from siblings like scan_site.

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

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

The description implies usage: you have a scan id and want the scan data. It does not explicitly state when to use this tool over alternatives like scan_site or ask, nor does it provide exclusions. The context is clear but relies on inference.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable behavioral context: scans may take ~60 seconds and larger scans switch to an async ID-based flow requiring get_scan polling. It also discloses the return structure (scores and per-check findings) beyond what annotations provide.

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

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

The description is two sentences: the first states the action and expected outputs, the second covers latency and the asymmetric fallback. Every clause adds information, with no redundancy or 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?

Given the rich annotations, full schema coverage, and existence of an output schema, the description completes the picture by explaining the tool's purpose, output composition, latency, and the polling behavior for long scans. There are no obvious gaps in what an agent needs to know to invoke and use this tool correctly.

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

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

The input schema already documents both parameters (url and pageLimit) with descriptions, achieving 100% coverage. The tool description adds no additional parameter-specific meaning beyond what the schema provides. Baseline 3 is appropriate because the schema carries the full burden.

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

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

The description names the specific resource (agent-ready.dev scanner), lists the concrete outputs (Vercel score, llmstxt.org score, per-check findings with remediation hints), and implicitly differentiates from sibling get_scan by describing the polling flow for larger scans. This is a specific verb+resource statement with clear 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 explicitly tells the agent that for larger scans the tool returns a scan ID and that polling with get_scan is the follow-up, which is a clear usage directive. It does not explicitly say when not to use this tool versus ask, but the purpose is clearly scoped to scanning, so the guidance is sufficient.

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