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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered by structured data. The description adds the meaningful operational constraint that it reads live from HMRC MTD and requires that integration to be connected. It says nothing about rate limits, HMRC-side errors, or what happens when no liabilities exist, so with annotations carrying the safety bar this sits at an adequate 3.

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?

Two tight sentences: the operation and return content come first, then usage triggers and the connection prerequisite. Every clause carries information, and nothing is padded.

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?

There is no output schema, but the description compensates by stating the shape of the return (amounts owed and due dates). Parameters and prerequisites are fully covered between the description and a 100%-covered schema. The only missing piece is guidance on how liabilities differ from obligations/payments, which is a sibling-routing gap rather than a calling gap.

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 all three parameters (from, to, company) are documented in the schema, including defaults and the one-year capping behavior. The description adds nothing about parameter usage, so the baseline 3 applies.

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+resource ('Read the company's VAT liabilities') and defines what a liability is (amounts HMRC says are owed, and due dates), sourced 'directly from HMRC MTD'. It does not explicitly distinguish itself from the close siblings get_hmrc_vat_obligations and get_hmrc_vat_payments, so an agent must infer the boundary.

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 concrete trigger phrasings ('how much VAT do I owe HMRC', 'what's outstanding on my VAT account') plus a hard prerequisite ('Requires HMRC MTD connected'), which is clear usage context. It stops short of naming alternatives to use instead for obligations or payment history, so there is no explicit exclusion guidance.

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