UK Data: UK NHS and charities

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely new context in the credit cost, which the annotations do not carry. It says nothing about rate limits, error behavior for unknown numbers, or how up-to-date the register data is, so it stops short of rich behavioral disclosure.

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?

One front-loaded sentence with the resource, the identifier and the returned fields, plus a parenthetical cost note. Nothing is redundant and no sentence needs to be read twice.

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 single-parameter, read-only lookup with no output schema, the description usefully enumerates the main fields returned, which is the main completeness risk here. It is not fully complete because it omits what happens on an unknown or non-charity number, but the essentials for calling the tool are present.

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 100% but the single parameter's schema text is only 'string, required', so the description's phrase 'registered charity number' is what actually tells the agent what to supply. That is a real addition, but it gives no format hint (digits only, leading zeros, length), so it does not fully compensate for the thin schema wording. Baseline 3 is appropriate.

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 names the specific resource (Charity Commission register details), the key input (a registered charity number) and the returned fields (status, income, expenditure, activities, address), so the agent knows exactly what it retrieves. It is unambiguous against siblings such as company_profile or fca_search because the register is named, though it never explicitly states the contrast.

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?

There is no when-to-use guidance, no mention of when a sibling like company_search would be preferable, and no prerequisites or failure conditions (e.g. invalid or non-charity numbers). The only usage-relevant information is the credit cost, which is about pricing rather than tool selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered by structured data. The description adds one genuinely new piece of behaviour, the cost of 1 credit, but says nothing about result volume, pagination, or the default active-only filtering that materially affects what comes back.

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?

A single front-loaded sentence naming the resource, its scope and the lookup keys, with the cost appended in parentheses. Nothing is redundant, though the credit note is stylistically separate and could be folded in more cleanly.

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?

Five optional parameters, no output schema, and rich annotations mean the description doesn't need to explain return values or safety. It covers the domain and the main query axes adequately; the only real omission is behaviour around the status default and result limits, which an agent could still discover from the schema.

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%, so all five parameters are documented in the schema, which sets the baseline at 3. The description restates three of them (name, postcode, role) without adding format hints, and does not mention status or limit at all. It therefore adds little beyond the schema.

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 resource (NHS organisations: trusts, GP practices, pharmacies, hospitals) and its source (the ODS directory), plus the three search keys. That is clear and concrete. It does not name or distinguish from near-neighbours such as cqc_search or postcode_lookup, so it falls short of a 5.

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 'by name, postcode or role' implies the lookup contexts in which the tool is appropriate, so usage is implied rather than stated. There is no explicit when-not guidance and no routing to alternatives that overlap (cqc_search for care providers, postcode_lookup for address data).

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