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

Goes well beyond the annotations: it discloses the real-world irreversibility ('sends a real appeal to a real council... cannot be undone'), the payment gate and £7.99 price, the automatic filing after payment, and the required name/postal address. The annotations only flag destructive/non-idempotent; the description explains what is actually destroyed and what the agent must relay to the user.

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?

Four dense sentences front-load the action and the irreversible warning, then move to payment and parameter requirements. Every sentence carries actionable information, though the payment/checkout instruction is slightly compressed.

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 destructive write tool with no output schema, it covers the preconditions, the payment branch, the returned checkout_url, and the correct agent behavior. Nothing needed to invoke it correctly or report results 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 coverage is 67% and the description compensates: it clarifies that name and address are required and that they can come from the saved profile or be passed in, which is not evident from the schema alone. The 'id' parameter is left implicit but is unambiguous from the tool's purpose.

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 and resource ('Files the drafted appeal for a notice') and immediately scopes it ('in the account holder's own name'), which distinguishes it from read-only siblings like get_notice, check_notice, and lookup_appeal_status. An agent can tell it is the only sibling that actually submits.

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?

Gives an explicit precondition ('confirm with the user first') and the payment branch condition ('If the notice is unpaid and not covered by a plan'). It does not name a sibling alternative, but no sibling performs filing, so the when-to-use context is effectively complete.

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