Generate Gap Report

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It reveals the two output formats but says nothing about whether the report is returned inline or written to disk, whether the operation is read-only or mutating, what permissions/tokens are needed, or how malformed audit_result objects are handled. The repeated 'defensive use only / authorised to audit' sentences add authorisation framing but no operational behaviour.

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 purpose is correctly front-loaded in the first sentence, but the remaining two sentences restate the same authorisation requirement almost verbatim ('sites/projects you own or are authorised to audit' vs 'websites, endpoints, or local projects that you own or have explicit written authorization'). That redundancy occupies roughly two-thirds of the description without adding 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 explained, and the tool is a straightforward transform. Still, for a tool with no annotations, an undocumented opaque input object, and a nested schema, the description leaves the caller unsure where to obtain a valid audit_result and what it must include.

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 0% for two parameters, so the schema offers no meaning beyond types and an enum. The description never explains what the free-form 'audit_result' object must contain (which fields, from which tool) — a significant gap given additionalProperties is true and the object is nested. Only 'format' is loosely reflected via '(Markdown or JSON)', which the enum already conveys.

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 and resource: 'Generate a formatted gap analysis report (Markdown or JSON) from an audit result.' That is enough to separate it from siblings like scan_privacy_policy or run_full_audit, which produce findings rather than format them. It stops short of explicitly naming the producing sibling, so the differentiation is inferable 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 phrase 'from an audit result' implies this is a post-audit formatting step, which is useful implied routing. However, there is no explicit guidance such as 'call after run_full_audit' or any when-not-to-use condition; the only stated constraint is the authorisation warning, which is about legality, not tool selection.

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