Agent Ready

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds real value by disclosing the payload's content: measurement definition, point value, and remediation pointer. It stops short of describing behavior on unmatched or ambiguous names.

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, and the return-content summary is front-loaded ahead of the parameter guidance.

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 single-parameter read-only lookup with full schema coverage, the description is nearly sufficient, covering purpose, input source, and return content without an output schema. It omits failure/ambiguity behavior, which matters given the fuzzy name matching implied by 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 coverage is 100%, so the baseline is 3, but the description goes beyond the schema by specifying the name's provenance ('as it appears in a report') and giving a concrete example string. It does not reconcile the tension with the schema's allowance for 'a few words from it' (fuzzy matching).

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 (explain) and resource (one Agent Ready check), and enumerates what the explanation contains: what it measures, its weight, and where to read the fix. It does not explicitly differentiate itself from siblings like get_report or get_scoring_method, though the name-based scope makes the distinction inferable.

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?

"Pass the check name as it appears in a report" implies the workflow (call a report first, then drill into a check) but never states when to use this versus get_report or get_scoring_method, nor when not to use it. Usage is implied rather than prescribed.

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, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds one useful behavioral note — this fetches rather than re-runs a scan, so there is no scan cost — but says nothing about failure behavior when the id/link is invalid or the report is missing.

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 sentence, front-loaded with the verb and resource, with each clause contributing (scope: already run; input: link or id; constraint: no rescan). 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 one fully documented parameter and complete annotations, the call mechanics are clear. However, there is no output schema, so the description should indicate what a fetched report contains or its shape, and it is silent on error behavior — leaving a gap for a retrieval 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 description coverage is 100% and the single 'report' parameter is already documented as a URL or id in the schema. The description restates the same accepted forms ('report link or id') without adding format, validation, or id-syntax detail, 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 a specific verb (Fetch) and resource (a report already run) and scopes it to fetching by link or id. The clause 'without scanning again' implicitly separates it from scan_website, though it never names that sibling 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?

'that was already run' and 'without scanning again' imply the condition for use (a report must already exist) and hint at the alternative, but the description never states what to do when no report exists — e.g. use scan_website instead. Usage is suggested rather than prescribed.

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 this is a safe read-only, closed-world lookup, so the bar is lower. The description adds that the payload is the full methodology (weights plus all checks), implying a static reference rather than a per-site computation, but does not say so explicitly or indicate size/format.

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 compact sentence with no filler, and the most useful content (areas, weights, checks) is front-loaded. The clause structure is slightly elliptical, 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?

With no output schema and no parameters, the description carries the burden of telling the agent what comes back, and it does: scored areas, weights, and every check. Only the static nature and rough shape of the response remain 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?

The tool takes zero parameters, so the baseline is 4. Nothing in the description invents parameters or suggests inputs are needed, which is correct.

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 exact content returned: scored areas, their weights, and every check. It reads as a noun phrase without an explicit verb, but for a no-input reference tool the resource is unambiguous and clearly distinct from scan_website or get_report.

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 trailing clause 'so a score can be explained' implies the use case (explaining how a score was computed), but there is no explicit when-to-use framing and no routing away from siblings like explain_check, which likely covers a narrower question.

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?

Description adds valuable context beyond annotations: return structure (overall score, per-area scores, top finding per area, report link), performance expectation (5-20 seconds), and scope constraint ('public website'). Annotations declare readOnlyHint=false and openWorldHint=true, which the description is consistent with. Minor gap: it doesn't explain the caching behavior that 'fresh' implies.

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 plus a concise output sentence, front-loaded with the core purpose and score scale. Free of filler, though the long enumeration of scoring areas makes it slightly dense.

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?

Covers what it returns (compensating for no output schema) and the time cost, and the scope constraint is clear. A small gap remains around whether results are stored for retrieval via get_report, but overall an agent has what it needs to call it 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?

Schema coverage is 100% with detailed parameter descriptions, including examples for url and the 'fresh' caching semantics. The description adds nothing beyond the schema regarding parameters, 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 (score) and resource (public website) with the exact output (out of 100) and the dimensions evaluated. Clearly distinguishes from siblings: this is the scanning action, while get_report retrieves an existing report and get_scoring_method explains criteria.

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?

Implies when to use (to score a public website for agent readiness) and covers rescan behavior via the 'fresh' parameter semantics, but does not explicitly state when NOT to use it or point to siblings like get_report for existing results. Usage context is implicit rather than stated.

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