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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds meaningful context beyond annotations: 'it is read-only and does not vary a permit or decide that a variation/new permit is legally required', and it discloses the return content ('Returns changed fields, findings, official evidence and review actions'). This adds value without contradicting 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 two sentences plus a 'Do NOT use' sentence. Every sentence carries essential scope, behavioral, or exclusion information. It is not overly verbose, though it could be tightened slightly by removing redundant phrases like 'FREE' and 'official evidence' without losing meaning. Still, it is well structured and front-loaded with the core purpose.

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 tool with a nested input schema and an output schema, the description covers the essential operational context: when to use, what it does, what it returns, and what it doesn't decide. It doesn't explain the nested schema structure in detail, but the schema descriptions and output schema are present. The main gap is not explaining the 'found in official evidence' aspect, but overall it is complete enough for correct invocation.

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% according to context signals, so the description must compensate. It does by naming the modelled fields (location, activities, waste types, quantity, storage, treatment, operating hours) which map to the PermitOperationFacts properties, and by explaining the current/proposed comparison that maps to the scenario structure. It doesn't detail each parameter, but it provides the semantic link needed to understand what inputs are compared.

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 'FREE PERMIT-CHANGE IMPACT PREFLIGHT for an EXISTING England waste operation' and explicitly states it compares modelled fields like location, activities, waste types, quantity, storage, treatment, and operating hours. This clearly defines the verb (preflight), resource (permit-change impact), and scope. It also distinguishes from siblings by listing exclusions ('brand-new operation route, carrier registration, DWT receipt-reporting readiness').

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 explicitly states when to use: 'when both current and proposed operating facts are available' for an 'EXISTING England waste operation'. It also gives when-not guidance: 'Do NOT use for a brand-new operation route, carrier registration, or DWT receipt-reporting readiness', which maps directly to sibling tools. This is explicit when/when-not guidance with alternative categories.

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