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

The description adds substantial behavioral context beyond annotations: it discloses the cost (500 micro-dollar service credits per successful call), prerequisites (existing credits and a private Authorization header), idempotency nuance (reusing requestId for recovery vs. new billable operation), and privacy (without echoing values). This aligns with the idempotentHint annotation and adds practical 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?

The description is three sentences long, front-loading the core purpose, then addressing cost/prerequisites and recovery. It is efficient, with no redundant or vague statements, and every sentence contributes critical operational 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?

Given the tool's complexity (nested input, paid operation, prerequisite preparation, idempotency) and the presence of an output schema, the description covers all essential aspects: purpose, cost, prerequisite, auth, and recovery behavior. The output format is handled by the output schema, so nothing critical 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 67% (requestId and maxPriceMicroUsd have descriptions, input does not). The description adds some context about requestId usage ('Reuse prepared arguments for recovery') and billing implications, which clarifies parameter intent. However, it does not elaborate on the input object or maxPriceMicroUsd beyond the schema, so it only partially compensates for the coverage gap.

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's function: 'Review supplied response headers for selected security and CORS issues without echoing values.' It specifies the verb (review), resource (response headers), and scope (security and CORS), and distinguishes itself from sibling audit tools like security_cookie_audit and security_csp_audit by focusing on headers broadly.

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 gives explicit usage guidance: 'First use agent_utilities_prepare for this tool' and 'Reuse prepared arguments for recovery; a new requestId is a new billable operation.' It does not explicitly compare to alternatives, but the name and sibling context make the differentiation clear. The lack of explicit 'when not to use' slightly reduces the score.

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