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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful context beyond those: what metadata fields will be returned, that it includes a complete structured table of contents, and that no authentication is required. It also names the data source and licence, which helps the agent assess suitability. It does not cover rate limits or response ordering, but given the annotations the description carries enough behavioral context.

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 front-loaded with the tool's core function and return contents before moving to usage guidance and attribution. It is dense but not bloated; the two examples are repetitive with the schema examples but still concretely illustrate a valid call. The data source/licence sentence is useful but slightly beyond the core behavioral description.

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 read-only, three-parameter tool with a full input schema and an output schema, the description is complete: it explains what the tool returns, how to obtain required identifiers, gives examples, and declares auth/licensing context. The presence of an output schema means detailed return-value documentation is not needed in the description. An agent has everything required to select and invoke 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?

Schema description coverage is 100%, and each parameter already has a clear description and example in the schema. The description's examples mirror the schema examples rather than adding new semantic detail, so it does not compensate or extend beyond what structured input schema already provides. This meets the baseline but does not surpass it.

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 states a specific verb ('Get'), resource ('UK legislation'), and identification method (type/year/number), then enumerates the exact fields returned. It clearly differentiates from ukleg.legislation.search and ukleg.legislation.recent by scope and purpose, even pointing to search as the way to find identifiers. Examples further anchor what the tool does.

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 instructs the agent to use ukleg.legislation.search to find the correct type, year, and number before calling this tool, which is concrete when-to-use guidance. The two worked examples (Climate Change Act, Data Protection Act) give unambiguous usage patterns. This is as explicit as usage guidance gets for this tool.

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