UK Business Tools - Ledgerhall

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is clear. The description adds value by detailing the specific data returned (trustees, income, insolvency flags, etc.), providing behavioral context beyond the 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?

Three concise sentences, front-loaded with the core purpose. Every sentence adds value with no wasted words.

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?

The description lists the main data fields returned. With an output schema present, the agent can infer the full structure. It is adequate for a single-parameter lookup tool, though it does not mention error handling or pagination.

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?

The input schema already has full description coverage (100%) for the only parameter, charity_number. The description reinforces this by stating it is returned by charity_search, adding useful context for the agent.

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 clearly states the tool fetches the full Charity Commission profile for a charity number, listing specific data fields like trustees, income, expenditure, etc. It is easily distinguished from its sibling dd_charity_search, which is used to find charity numbers.

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 advises using charity_search first to find the charity number, providing clear guidance on the prerequisite step. However, it does not mention when not to use this tool or any alternatives beyond the search tool.

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 indicate read-only, idempotent, non-destructive, and open-world hints. The description adds crucial behavioral context: the upstream endpoint returns the full list, and pagination is applied client-side via offset/limit. This information is beyond what annotations provide and helps the agent understand the tool's behavior.

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 sentences with no fluff. The most important information is front-loaded: what it does and what it returns. Every sentence adds value, including the sibling reference and the pagination detail.

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 search tool with existing annotations, schema, and output schema, the description is complete. It covers the action, return fields, sibling tool usage, and pagination behavior. No gaps are evident.

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?

The input schema has 100% coverage with descriptions for all parameters (query, limit, offset). The description adds value by explaining that pagination is client-side, which clarifies the role of limit and offset. This is a useful addition beyond the schema's basic descriptions.

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 clearly states it searches the Charity Commission register by name or keyword, and specifies the returned fields (registration number, status, registration date). It distinguishes from the sibling tool dd_charity_profile by directing users to use that for full details once they have the charity number.

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?

Explicitly advises when to use this tool (search by name/keyword) and when to use the alternative (charity_profile for full details after obtaining the charity number). Also explains the pagination behavior, helping agents decide on offset/limit usage.

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, openWorldHint, idempotentHint. Description adds that resigned officers are excluded and pagination is internal, which are useful behavioral details beyond what annotations provide.

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 sentences: first clearly states purpose, second adds essential details (exclusions, pagination). No redundant information; every sentence earns its place.

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?

Given tool has an output schema, the description fully covers the input and behavior without needing to explain returns. Complexities like pagination and exclusions are addressed, making it complete for the tool's scope.

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%, baseline 3. Description adds meaning by stating that start_index and items_per_page are ignored and gives an example company_number format. This clarifies the role of parameters 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?

The description clearly states it 'Fetch active officers for a Companies House company number' and specifies the returned objects (directors, secretaries, etc.) and excludes resigned officers. It is distinct from sibling tools like dd_company_profile, which covers broader company data.

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?

Provides explicit guidance that pagination is handled internally and warns not to pass items_per_page or start_index, only company_number. Lacks explicit comparison to alternatives but strongly implies correct usage.

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=true, idempotentHint=true, etc. The description adds valuable details about the return data (status, address, SIC codes, compliance flags, charges) which is beyond what annotations provide. No contradiction.

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?

Three sentences: purpose, return data, usage tip. Front-loaded, no filler, every sentence adds value.

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?

Given single required parameter, existence of output schema, and clear annotations, the description fully covers what the tool does, what it returns, and its prerequisite. No gaps.

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% with a clear description of the company_number parameter. The description adds context that the number comes from company_search, providing useful integration hint 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?

Description clearly states 'Fetch the full Companies House profile for a company number', with specific verb and resource. It distinguishes from sibling tools like dd_company_search (used to find the company number) and other company-related tools.

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?

Explicitly advises to use company_search first to obtain the company number, providing clear prerequisite and integration guidance. Does not list all alternatives but context is sufficient.

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 indicate readonly, idempotent, non-destructive behavior. Description adds behavioral context: flags overseas corporate PSC entries as risk signals and returns an explanatory note for widely-held PLCs with no registrable PSC.

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?

Three sentences with high information density: first sentence states core purpose, second lists returned fields, third notes special behaviors. No wasted words.

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?

Tool has simple input (one parameter) and output schema exists (not shown). Description covers purpose, returned data, and special cases. No gaps for a straightforward read tool.

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 for parameters is 100%; company_number is described in the schema as 'Companies House company number (8 digits...) Returned by company_search.' The description does not enhance parameter semantics 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?

Description clearly states it fetches Persons with Significant Control (beneficial ownership) and specifies returned fields (natures of control, nationality, country of residence). The tool name and behavior differentiate it from sibling tools like dd_company_profile or dd_company_officers.

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?

Usage context is implied by the purpose (for beneficial ownership data), but no explicit when-to-use, when-not-to-use, or alternative recommendations are provided.

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 readOnly, idempotent, non-destructive. Description adds pagination behavior and return content, which are beyond the 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?

Three sentences with no redundancy. Front-loaded with purpose, then return fields, then usage guidance.

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?

Output schema exists, so return values are covered. Description mentions key fields returned and pagination behavior. Could have mentioned available filters but schema covers them.

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% with descriptions for all 5 parameters. Description does not add additional meaning beyond the schema, only context about pagination.

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?

Clearly states it searches Companies House register by company name or keyword. Lists specific fields returned and distinguishes from sibling tool dd_company_profile.

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?

Explicitly tells when to use company_profile instead (after obtaining company number) and provides pagination instructions (re-call with start_index+items_per_page).

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 indicate read-only, idempotent, non-destructive behavior. The description adds value by detailing the specific data returned (reason, Act, period, company names) beyond what annotations provide.

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?

Three sentences: purpose, return details, usage advice. Each sentence adds essential information without redundancy. Front-loaded with the core action.

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?

Given the tool's simplicity (one parameter, output schema exists, strong annotations), the description fully covers what the agent needs: what it does, what it returns, and how to prepare the input.

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%, so baseline is 3. The description adds context that the officer ID comes from 'disqualified_search', which helps the agent understand how to obtain the parameter value.

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 clearly states the verb 'Fetch', the resource 'full disqualification record', and the input 'by officer ID'. It distinguishes itself from the sibling 'dd_disqualified_search' by implying it is the follow-up step.

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 instructs to use 'disqualified_search first to find the officer ID', providing clear sequential guidance. It does not list alternatives but the context from sibling tools makes the workflow clear.

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 provide readOnlyHint, openWorldHint, idempotentHint. Description adds that queries must be individual names, returns specific fields (names, DOB, disqualification period, officer IDs), and that company names fail. Doesn't detail pagination behavior, but that's covered by schema.

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?

Five sentences, front-loaded with core purpose, no unnecessary words. Highly efficient and well-structured.

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?

Given an output schema exists, the description need not detail return values. It covers purpose, usage guidelines, input constraints, and result summary. Fully sufficient for a search tool.

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 has 100% coverage with clear descriptions. The description adds value by clarifying that the query must be a person's name, not a company name, which is not explicit in the schema description.

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?

Description clearly states the tool checks if an individual is banned from being a UK company director, which is specific and distinguishes it from sibling tools like dd_company_search and dd_disqualified_profile.

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?

Explicitly says when to use: 'Use this tool when asked to check disqualified, banned, or barred directors.' Also warns against using company names, which would return zero results.

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 indicate read-only, idempotent, non-destructive behavior. The description adds routing rules based on ID prefix, which is behavioral context beyond 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?

Very concise, using a short intro and bulleted list. Every sentence is informative with no redundancy.

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?

Given the simple single-parameter tool with full schema and output schema, the description adequately covers routing behavior. Minor omission: no mention of possible errors or limitations, but not critical for this tool.

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?

The schema already describes the id parameter format with 100% coverage. The description adds context that the id comes from search and elaborates on the prefix formats, adding value 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?

The description clearly states it fetches the full record for an ID returned by search, and lists four specific routing prefixes, distinguishing it from sibling tools that target individual registers.

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 implies use after a search (id returned by search) and explains routing by prefix, effectively guiding the agent to use this tool instead of separate per-register tools, though it does not explicitly mention alternatives.

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?

The description adds significant behavioral context beyond annotations: results are sorted by severity (winding-up orders first), each result includes a notice_numeric_id, and the Gazette is the official UK public record with legal effect. This complements the annotations (readOnlyHint, idempotentHint, etc.) well.

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 concise with three well-structured paragraphs. The first sentence front-loads the core purpose. Subsequent paragraphs add necessary detail without verbosity. Every sentence adds value.

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?

The description covers the tool's purpose, notice types, sort order, output usage, and legal significance. It lacks mention of pagination or the max_notices cap (though schema covers it), and no error handling details. However, with annotations and output schema present, it is nearly complete.

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% with all parameters described in the schema. The description does not add new parameter details beyond schema but provides context like notice codes. As per guidelines, baseline 3 is appropriate since schema already handles parameter documentation.

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 clearly states the tool searches The Gazette's insolvency notice index by entity name. It specifies the resource (corporate insolvency notices) and action (search by name), and lists relevant notice codes. In the context of sibling tools like dd_gazette_notice (which likely retrieves a single notice), this tool is well-differentiated.

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 implies usage for searching insolvency notices but does not explicitly state when to use this tool over alternatives or provide exclusion criteria. No mention of prerequisites or preferred scenarios. The agent must infer from the context.

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, and destructiveHint, so the description does not need to restate safety. It adds value by describing the return type (JSON-LD linked-data record) and fields (parties, legal basis, court, full text), which goes beyond 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?

Two concise, well-structured sentences. First sentence states the core action, second explains what is returned and how to obtain the ID. No fluff, front-loaded.

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 simple tool with one parameter, annotations, and an output schema, the description fully covers purpose, usage prerequisite, parameter source, and return structure. Nothing 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 100% and the description reinforces the parameter's meaning by stating 'numeric notice ID' and tying it to the sibling tool output. The description adds context about the ID's origin, enhancing understanding.

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?

Clearly states 'Fetch the full legal wording of a Gazette notice by numeric notice ID.' It specifies the verb (fetch), resource (Gazette notice), and method (by numeric notice ID), and distinguishes from sibling tool dd_gazette_insolvency by implying a different step in the workflow.

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?

Explicitly directs users to 'Use gazette_insolvency first to find notice_numeric_id values,' providing a clear prerequisite and indication of when to use this tool versus its sibling.

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?

Without annotations, the burden falls entirely on the description. It mentions 'rendered prompt' and return format, but fails to disclose read-only nature, side effects, or authentication needs. Minimal 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?

Three concise sentences, front-loaded with purpose. No redundancy or filler. Every sentence adds distinct information.

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?

Adequate for a 2-param tool with output schema. Mentions return format ('messages array'). Lacks error handling or usage context (e.g., when name not found). Could briefly address alternatives.

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 has 100% coverage, but description adds value: 'Arguments should be provided as a dict mapping argument names to values' clarifies the structure beyond the schema's 'Optional arguments for the prompt'.

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 clearly states 'Get a prompt by name', providing a specific verb and resource. While it doesn't explicitly differentiate from siblings like dd_list_prompts or law_get_prompt, the purpose is unambiguous.

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?

No guidance on when to use this tool versus alternatives (e.g., dd_list_prompts for listing, law_get_prompt for legal prompts). The description lacks context for choosing this tool.

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?

Discloses geographic scope, result limit, input behavior (postcode extraction), and output fields beyond annotations (readOnlyHint, idempotentHint). No contradictions.

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?

Three front-loaded sentences with no superfluous information, efficiently covering purpose, scope, input advice, and output fields.

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?

Complete for a simple search tool: explains geographic scope, result limit, input preference, and return fields. Annotations cover idempotency, read-only, and open world. Output schema provides further details.

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?

With 100% schema description coverage, baseline is 3. The description adds 'UK property address or postcode. Postcode is most reliable: e.g. 'NG1 1AB'. Full address also accepted.' which adds value beyond 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?

The description states 'Search HM Land Registry Price Paid Index by postcode or address' with specific verb and resource, and distinguishes from sibling tools like company searches or property searches by focusing on price paid transactions.

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?

Provides clear context: covers England and Wales only, returns up to 10 results, and suggests postcode is most reliable. However, it does not explicitly exclude alternatives like prop_ppd_transactions.

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?

Describes return format (JSON with prompt metadata), but lacks mentions of side effects or authentication. Sufficient for a read-only list tool with no 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?

Two sentences, zero wasted words. Front-loaded with key action. Perfectly concise.

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?

Fully adequate given zero parameters and presence of output schema. No missing information for a simple list tool.

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?

No parameters in input schema; description correctly indicates no parameters needed. Baseline score 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?

Clearly states 'List all available prompts' with specific verb and resource. Distinguishes from sibling 'law_list_prompts' by domain prefix 'dd'.

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?

No explicit guidance on when to use vs alternatives like 'law_list_prompts'. Usage context is implied but not detailed.

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 indicate readOnly, openWorld, idempotent, and nondestructive hints. The description adds context about parallel search across multiple registers and the need to fetch full records. No contradictions with 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?

Two concise paragraphs clearly front-load the primary purpose. Every sentence provides necessary information without redundancy or waste.

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?

Given output schema exists, return values need not be detailed. Description covers usage and result handling well. Minor omission of edge cases (e.g., no results) but overall complete.

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 has 100% parameter description coverage with clear constraints. The description does not add meaning beyond the schema's query parameter description, but explains the return type (result IDs) and usage pattern.

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?

Description clearly states the tool searches all UK due diligence registers simultaneously, lists specific registers (Companies House, Charity Commission, etc.), and explains it returns result IDs for later fetching. It effectively distinguishes from single-register sibling tools like dd_charity_search and dd_company_search.

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?

Implicitly suggests use when needing to search multiple registers at once. Provides follow-up guidance to 'use fetch with each ID to retrieve the full record'. However, it does not explicitly mention when not to use or directly reference sibling alternatives.

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 indicate read-only, idempotent, non-destructive behavior. The description adds value by disclosing that the returned trading address often differs from Companies House address, which is a useful behavioral trait for due diligence. No contradictions.

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 concise sentences: the first states purpose, the second describes return value and a key insight. No wasted text.

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?

Given the presence of an output schema, the description covers input purpose, high-level return values, and an important usage note. It is complete for a simple validation tool.

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%, and the schema description already explains accepted formats and normalization. The description does not add additional parameter context beyond what is in 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?

The description clearly states it validates a UK VAT number against the HMRC register and returns the trading name and address. It is specific and distinct from sibling tools, all of which are unrelated companies, law, property, or charity tools.

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 implies use for due diligence checks, noting the VAT address discrepancy signal. While it does not explicitly state when to use or not use vs alternatives, the sibling list shows no other VAT validation tool, so context is clear.

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 indicate readOnlyHint and idempotentHint, so the description adds value by detailing the return content (title, dates, sections). No contradictory or missing behavioral traits.

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 concise sentences. First sentence captures purpose, second specifies outputs and sibling tools. No filler content.

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?

Given the presence of an output schema, the description sufficiently explains the tool's role as an index pointer for GOV.UK content, and how it orchestrates with other tools.

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?

The only parameter 'base_path' has a description in the schema with example format. Schema coverage is 100%, so the description does not need to add more. 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 clearly states it gets metadata and navigable section index for a GOV.UK page, listing specific outputs (title, dates, sections). It also distinguishes itself from sibling tools like govuk_get_section and govuk_grep_content.

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 tells when to use this tool: to get the index first, then use govuk_get_section for reading a section or govuk_grep_content for searching. This provides clear guidance on alternatives.

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, and non-destructive. Description adds value by listing returned fields, though output schema exists. No contradictions.

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 efficient sentences, front-loaded with action, no unnecessary words.

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?

Given output schema exists, sibling tool referenced, and return fields mentioned, description is complete for a lookup tool.

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% and schema description already explains slug parameter well. Description does not need to add more; 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?

Description clearly states it gets a UK government organisation profile by slug, lists return fields (name, acronym, type, etc.), and distinguishes from sibling tool govuk_list_organisations.

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?

Explicitly instructs to use govuk_list_organisations to browse organisations and discover slugs, providing clear when-to-use guidance.

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=true, idempotentHint=true, and destructiveHint=false. The description adds that it returns HTML content, which is useful but not deeply behavioral. No contradictions.

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 sentences, no wasted words. The purpose and usage are clearly front-loaded.

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?

The description provides the necessary context given the output schema exists and annotations cover safety. It could mention that the HTML is from a specific section, but it's sufficient for a simple read tool.

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% with both parameters described. The tool description does not add extra meaning beyond the schema, so baseline score of 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?

The description clearly states 'Get the HTML content of one named section of a GOV.UK page,' which is a specific verb and resource. It also indicates a prerequisite (use govuk_get_content first), distinguishing it from other GOV.UK tools.

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 gives explicit usage guidance: use govuk_get_content first to get anchors, then call this tool with the anchor. While it does not list when not to use, the workflow is clear and effectively guides the agent.

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 indicate readOnlyHint=true and idempotentHint=true. The description adds that it returns a list of {anchor, heading, snippet, match} hits and that pattern compilation failure falls back to literal substring, which is useful beyond 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 only 4 sentences, front-loaded with purpose and return structure, and each sentence adds value. No wasted words.

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?

With 100% schema coverage, an output schema, and good annotations, the description covers purpose, usage, return format, and fallback behavior. It is complete for an LLM to select and use the 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%, so the description does not need to add much. It reinforces that pattern is regex, but provides no additional meaning beyond the schema. Baseline of 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 clearly states 'Find body sections in a GOV.UK content item matching a pattern', specifying verb and resource. It distinguishes from sibling tools like govuk_get_section by noting that it returns snippets for the LLM to decide which sections to read.

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 says 'Use this when answering content-based questions ... rather than navigating by section number', providing clear context. It falls short of a 5 because it does not mention specific alternatives or when not to use it.

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 indicate read-only, idempotent, non-destructive. Description adds that it returns a paginated list including slug, acronym, type, and status, enhancing transparency without contradiction.

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 sentences, each earning its place: first states purpose, second adds return details and usage guidance. No redundancy.

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?

With an output schema present and annotations covering safety, the description provides sufficient context: purpose, return fields, and usage for a simple paginated list tool.

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 covers both parameters (page, per_page) with descriptions and defaults at 100% coverage. Description doesn't add extra meaning beyond schema, so baseline 3.

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 clearly states 'List all UK government organisations registered on GOV.UK' with a specific verb and resource, and differentiates from siblings by mentioning slugs for use with related tools.

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?

Explicitly tells when to use: 'browse the full government structure or discover slugs for use with govuk_get_organisation or govuk_search filters'. No explicit when-not, but clear context.

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, and destructiveHint=false. The description adds that it uses the postcodes.io public API with no key required, and lists the types of administrative geography returned (local authority, region, constituency, NHS region). This provides useful behavioral context beyond the 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 concise: three short paragraphs, each serving a distinct purpose (core action, use cases, API details). No redundant sentences; every sentence adds value.

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?

Given the tool's simplicity (one required parameter, no enums, output schema present), the description covers purpose, usage context, and external API behavior. Annotations cover safety and idempotency. Nothing essential 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?

The input schema has 100% coverage and already describes the parameter (postcode) with format examples. The description does not add additional semantic detail beyond what the schema provides. According to guidelines, with high schema coverage the baseline is 3.

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 clearly states the tool's purpose: 'Look up a UK postcode to retrieve its local authority, region, constituency, and other administrative geography.' It uses a specific verb ('look up') and identifies the resource (postcode) and output types. No sibling tool performs this function, so it is well distinguished.

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 provides explicit use cases: 'Useful for determining which council area, parliamentary constituency, or NHS region a postcode falls within' and 'commonly used to direct users to the correct local service on GOV.UK.' While it does not state when not to use it or name alternatives, the context is clear and sufficient given the absence of similar tools.

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=true and destructiveHint=false. The description adds behavioral context: it returns a list of matching items with specific fields, uses the official Search API, and implies idempotent behavior. No contradiction with 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 concise (three sentences) without unnecessary verbiage. It front-loads the main purpose and returns to details, making it easy to scan. Every sentence adds value.

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?

Given the tool complexity (6 parameters, output schema exists), the description covers the essential behavioral aspects: search function, return fields, filter options. It does not detail pagination beyond parameters, but the output schema likely covers that. Adequate for a search tool.

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%, and the description goes beyond by explaining the meaning and common values for 'filter_format' and 'filter_organisations'. It also contextualizes the 'query' parameter. The 'count' and 'start' parameters are adequately described in 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?

The description clearly states it searches GOV.UK's 700k+ content items using the official Search API. It specifies what is returned (title, description, link, etc.), aligning with the tool name and title. It distinguishes from sibling tools like 'gov_govuk_get_content' which retrieve a specific item.

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 provides explicit guidance on using filters ('filter_format', 'filter_organisations') with examples of common values. It implies usage for broad searches, but does not explicitly state when to use alternatives (e.g., 'gov_govuk_get_content' for a single item), though sibling context suggests other purposes.

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 indicate read-only and idempotent behavior. The description adds context: returns specific fields, notes summary truncation with a check field, and explains parameter behavior, all consistent with 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?

Front-loaded with usage condition, then return fields, parameter details, and follow-up suggestions. Each sentence adds value with no redundancy.

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?

Given output schema exists, description covers key behaviors and connections to sibling tools. Provides sufficient guidance for correct tool invocation and follow-up actions.

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%. The description adds meaning by explaining bill_id source, max_summary_chars default and adjustment advice, and the summary_truncated response field.

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 clearly states the tool's purpose: use when you have a bill_id from bills_search_bills and want full detail. It distinguishes from sibling tools by specifying the source of the bill_id.

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?

Explicitly states when to use (have bill_id), what it returns, and provides post-call alternatives (parliament_search_hansard, bills_search_bills). Also explains max_summary_chars parameter usage.

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 indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds that it returns a 'paginated page of bill summaries' and that it is an 'Authoritative source for UK parliamentary bill status,' which provides context beyond annotations. No contradictions.

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 three sentences, front-loaded with the imperative use case, no wasted words. Every sentence adds value: purpose, return value and follow-up, and authority.

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?

Given the tool has 6 parameters (1 required), 100% schema coverage, and an output schema, the description is complete enough. It covers the search purpose, pagination, follow-up tool, and data source, without needing to detail the output schema separately.

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 each parameter is documented. The description adds value by providing usage guidance for 'session' (NOT a year string) and 'limit' (raise up to 100 for bulk exports), which builds on 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?

The description clearly states the verb ('search'), resource ('UK parliamentary bills'), and the filtering dimensions ('by keyword, session, house, or legislative stage'). It differentiates from the sibling tool 'bills_get_bill' by instructing to use that for full detail.

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 says 'USE THIS TOOL WHEN' and directs to call 'bills_get_bill' for more detail, providing clear context. It also mentions pagination usage. However, it does not explicitly exclude alternative sibling tools for related but different tasks (e.g., law_legislation_search), though the domain is distinct.

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 indicate readOnly, idempotent, and non-destructive. The description adds value by detailing the return format (list of {eId, snippet, match}), explaining pattern compilation fallback to substring search, and advising on next steps. No contradictions with 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 concise and well-structured: starts with a bold usage directive, then describes output format, use case, alternative, and pattern behavior. Every sentence adds value with no redundancy.

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?

Given the tool's complexity (regex search, multiple parameters, interaction with other tools), the description is complete. It explains the return format, pattern fallback, and next steps. Although an output schema exists, the description does not need to replicate it; the key details are covered.

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%, so all params are well-described in the input schema. The description adds minimal extra context (e.g., 'small per-paragraph snippets' and the pattern fallback behavior), but the schema already covers the fallback and other details. 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 clearly states the tool's purpose: to search within a UK judgment by pattern. It specifies the action (grep), the resource (judgment text), and distinguishes it from sibling tools like `judgment_get_index` and `judgment_get_paragraph`.

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 tells when to use this tool (when you have a judgment slug and want to search for a pattern), provides a use case, mentions what to do after calling (read full paragraphs), and names an alternative for paragraph-number navigation (`judgment_get_index`).

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 indicate read-only, idempotent, non-destructive behavior, which the description reinforces. It adds valuable context: coverage from early 2000s, TNA as authoritative source, and caveats about ignored date filters — exceeding annotation expectations.

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 well-organized and efficient: key usage first, then post-call workflow, filtering advice, coverage notes, and a final authoritative source note. Every sentence adds value, and the structure is front-loaded for quick scanning.

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?

Given 8 parameters, rich schema, and output schema, the description covers all essential aspects: purpose, parameters usage, downstream tools, filtering strategies, coverage limitations, and data freshness. An agent can confidently use this tool with no gaps.

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?

Despite 100% schema coverage, the description adds crucial practical details not in the schema, e.g., how to format judge names (avoid honorifics), best practices for limit, and a warning that from_date is currently ignored. This significantly enhances usability.

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 'USE THIS TOOL WHEN searching UK case law by party names, court, judge, date, or free-text query,' clearly specifying the verb and resource. It distinguishes the tool from sibling tools like judgment_get_header or citations_resolve by stating its search role and guiding downstream usage.

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 provides explicit when-to-use guidance, post-call steps (pass slug to specific tools), and strategies for narrowing results (court+year filters). It also warns against supplementing with web search, making usage boundaries clear.

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?

Discloses all behavioral traits beyond annotations: no network call, formats per OSCOLA 4th edition, refusal conditions (upstream_validation), and role as guard against fabrication. Annotations already indicate readOnly and idempotent, but description adds critical 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?

Concise yet comprehensive; uses bold/indentation for emphasis. Every sentence earns its place, covering purpose, usage rules, parameters, and failure modes without redundancy.

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?

Given the tool's complexity (14 params, high schema coverage, output schema exists), the description fully covers failure modes, input provenance, formatting authority, and guardrails. No gaps.

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?

With 100% schema description coverage, the description adds significant meaning: explains that 'raw' preserves EU retained law distinctions, 'confidence' refusal logic, 'resolved_url' requirement for neutral citations, and overall that all fields must come from citations_resolve.

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 explicitly states the tool's function: 'produce the correctly formatted OSCOLA citation string' as a follow-up to citations_resolve. It clearly distinguishes itself from siblings by specifying the exact role in the pipeline.

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?

Provides explicit when-to-use (after citations_resolve), when-not-to-use (confidence 0.0 or missing resolved_url), and what to do instead (surface failure, ask user). Warns against constructing fields manually, preventing misuse.

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?

The description discloses behavioral traits beyond annotations: 'Fetches the judgment XML from TNA and parses all OSCOLA citations within. Returns citations grouped by type, deduplicated and sorted.' Annotations already indicate read-only, idempotent, non-destructive; description adds valuable context on data source and processing.

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 concise (6 sentences) and front-loaded with the key purpose. Every sentence adds value: purpose, process, output, and post-usage instruction. No wasted words.

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?

Given the tool's low complexity (single parameter, simple output) and the presence of an output schema, the description covers all necessary information: what it does, how input is used, what output looks like (grouped, deduplicated, sorted), and how to proceed after. Annotations further confirm safety and idempotency.

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% with description. The description adds significant meaning: provides examples ('uksc/2024/12'), clarifies source ('use the 'uri' field from case_law_search results'), and specifies what not to include ('Do not include the https://... prefix'). This goes well beyond the schema's own description.

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 clearly states the tool's purpose: mapping all citations (cases, legislation, SIs, retained EU law) from a judgment slug. It uses a specific verb ('map') and resource ('every citation it makes'), and distinguishes from siblings by mentioning follow-up with citations_resolve.

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?

Explicit usage guidance is provided: 'USE THIS TOOL WHEN you have a judgment slug and want to map every citation it makes.' It also instructs on the next step: 'AFTER calling, pass any individual citation through citations_resolve.' This clearly tells when to use and what to do after.

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?

The description goes beyond annotation hints (readOnlyHint=true, destructiveHint=false) by explaining default pure-regex parsing, optional model-based disambiguation via MCP sampling, and the fact that parsed citations may not confirm real documents.

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 well-structured with a clear call-to-action, bulleted list of supported citations, and logical flow. It is slightly lengthy but every sentence adds value; minor trimming could improve conciseness.

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?

Given the presence of an output schema, the description fully covers the tool's operation, parameter details, and post-usage guidance. It addresses the complexity of citation parsing and provides all necessary context for an agent to use it 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 coverage is 100%, and the description adds significant context: it explains the supported citation types for 'text', the default behavior and sampling mechanism for 'disambiguate', and the maximum character limit.

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 clearly states the tool's purpose: extracting and classifying OSCOLA citations from free text. It lists specific citation types and explicitly distinguishes from sibling tool 'citations_resolve' by advising to use it after parsing.

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 the tool (with free text), explains the optional disambiguate parameter and its implications, and directly recommends following up with 'citations_resolve' to verify document existence.

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 indicate readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: live HTTP HEAD check for neutral citations, confidence setting to 0.0 on non-200 response, raising ValueError for unrecognizable input, and the warning about not formatting with 0.0 confidence. No contradiction with 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 well-structured with a clear usage instruction at the beginning, followed by details and warnings. While it contains some repetition ('surface the failure...' appears twice), each sentence serves a purpose. It is front-loaded with the most important information.

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?

Given the simple parameter, full schema description, presence of output schema, and comprehensive annotations, the description is highly complete. It covers resolution behavior, error handling, interpretation of results, and even cites the authoritative source. No gaps identified.

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?

The single parameter 'citation' is fully described in the schema with examples. The description does not add significant semantic detail beyond the schema; it focuses on behavior and usage. Since schema coverage is 100%, baseline is 3.

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 clearly states the tool's purpose: parsing and resolving a single OSCOLA citation, returning parsed fields and a resolved_url. It explicitly differentiates from sibling 'law_citations_parse' by adding resolution, and provides a specific use case (use before construction).

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 provides explicit guidance on when to use the tool ('USE THIS TOOL BEFORE constructing an OSCOLA citation string...'), warns against fabricating citations, and details how to handle failures (confidence 0.0, surface failure and ask user). It also implies alternatives by noting the risk of formatting without resolution.

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=true, idempotentHint=true, and destructiveHint=false. The description adds value by stating that the tool fetches detail and member list 'in parallel', which is an implementation detail not covered by annotations, and provides a workflow hint. No contradictions with 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 three short sentences, each serving a distinct purpose: usage condition, action, and next-step guidance. It is front-loaded and contains no unnecessary words, making it efficient for an AI agent to parse.

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?

Given the presence of an output schema, the description does not need to explain return values. It sufficiently describes the tool's purpose (retrieve metadata and membership) and usage workflow. For a detail retrieval tool, this is complete and addresses the agent's decision-making needs.

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?

Input schema has 100% coverage with a clear description for committee_id: 'Committee ID from committees_search_committees results.' The description does not add any additional parameter information beyond referencing the same ID, so it meets the baseline without adding extra semantic value.

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 clearly states it retrieves 'metadata + current membership' for a committee, with a specific verb ('fetches') and resource ('committee detail and member list'). It distinguishes itself from sibling tools like law_committees_search_committees and law_committees_search_evidence by specifying the use case.

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 says 'USE THIS TOOL WHEN you have a committee_id and want the metadata + current membership', providing clear usage context. It also advises chaining with law_committees_search_evidence for evidence queries but does not explicitly exclude other alternatives or state when not to use.

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, and destructiveHint, so safety is clear. The description adds value by stating the tool returns 'committee summaries (name, house, active status, ID)' and reveals that query filtering is done 'client-side against committee names,' which is not evident from the schema alone.

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 concise with two sentences plus a short follow-up paragraph. It front-loads the core purpose ('USE THIS TOOL WHEN...') and every sentence adds necessary context without redundancy.

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?

Given the tool has an output schema (per context signals), the description appropriately summarizes returned fields and provides guidance on post-call actions. With four parameters, zero required, and clear sibling tools, the description fully covers usage context.

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 description enriches several parameters: for 'limit', it says 'Default 100 comfortably covers all currently-active UK select committees. Raise only for historical sweeps.' For 'query', it provides examples and notes client-side filtering. These details reduce ambiguity 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?

The description explicitly states 'USE THIS TOOL WHEN searching or listing UK parliamentary select committees by name, house, or active status.' It clearly identifies the verb (search/list), resource (select committees), and key filtering dimensions, distinguishing it from sibling tools like committees_get_committee and committees_search_evidence.

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 gives explicit when-to-use instructions and provides a clear workflow: 'AFTER calling, pass committee_id into committees_get_committee for current membership, or into committees_search_evidence to retrieve oral and written evidence submitted to that committee.' This guides the agent on next steps and alternatives.

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?

Description discloses pagination (one page, default 20), capping behavior for titles and witness lists, and re-call logic, adding value beyond readOnlyHint and idempotentHint 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?

Five sentences, front-loaded with core instruction, no redundant information, efficient and clear.

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?

Covers pagination, caps, and re-call pattern; presence of output schema reduces need to explain return values, but could hint at data freshness or evidence scope.

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% with detailed parameter descriptions; description does not add further parameter semantics beyond what schema already provides, meeting baseline expectation.

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?

Clearly states the tool returns oral and written evidence for a committee_id, distinguishing it from sibling tools like committees_search_committees and committees_get_committee.

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?

Explicitly instructs when to use (with a committee_id) and provides pagination guidance with re-call pattern, but does not specify when not to use or mention alternatives.

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 the tool as read-only, idempotent, and non-destructive. The description adds that it returns a rendered prompt as JSON with a messages array, providing some additional context but not significantly beyond the 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 concise with three front-loaded sentences. Every sentence adds value, with no unnecessary information.

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?

Given the simple tool with two parameters, extensive annotations, and an existing output schema, the description is complete. It explains the return format and the argument structure, providing all necessary context for an agent.

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%, so the schema already documents both parameters. The description adds that arguments should be a dict mapping names to values, which offers slight clarification but does not add substantial new meaning 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?

The description clearly states the tool retrieves a prompt by name and returns it as JSON with a messages array. However, it does not differentiate from sibling tools like 'dd_get_prompt', which has a similar name.

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 implies usage (when you need a prompt by name) but does not provide explicit guidance on when to use this tool versus alternatives or when not to use it.

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 indicate readOnlyHint, idempotentHint, destructiveHint=false. The description adds critical context: connects to HMRC sandbox by default, production endpoint via HMRC_API_BASE, credential requirements, and error behavior ('Raises if credentials are not configured'). No contradiction.

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 highly concise with 5 sentences, each serving a purpose. It is front-loaded with the usage condition, and no information is redundant. Every sentence earns its place.

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?

Given the single parameter, comprehensive annotations, and presence of an output schema (not shown but referenced), the description adequately covers input requirements, return values (mandated status, effective date, trading name), and setup details. No gaps.

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% with thorough parameter description. The tool description reinforces the 9-digit requirement and adds that 'GB prefix accepted and stripped automatically,' enhancing the schema's value. Baseline 3 + extra detail = 4.

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 clearly states the tool's purpose: 'USE THIS TOOL WHEN you have a 9-digit VAT Registration Number and need that business's Making Tax Digital VAT mandate status.' The title 'Check MTD VAT Status' aligns perfectly, and it is distinct from sibling tools like law_hmrc_get_vat_rate.

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 provides explicit usage criteria: requires a 9-digit VRN and checks MTD status. It does not explicitly mention when not to use or alternatives, but the specificity and unique functionality among siblings make the guidance clear.

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 indicate non-destructive, read-only, idempotent behavior. The description adds valuable context: the tool uses a static lookup table (Autumn Statement 2023) and may be outdated, advising verification for current rates.

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 concisely structured in three clear sections: usage instruction, return values, and important caveat. Every sentence adds value, with the most critical information front-loaded.

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?

Given the tool's simplicity (1 parameter, output schema exists) and full schema coverage, the description covers all necessary context: what it does, what it returns, data freshness limitation, and alternative tool for verification.

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% with the single parameter 'commodity_code' already described. The description does not add meaning beyond the schema's examples, so 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 explicitly states the tool's purpose with a specific verb ('get') and resource ('VAT rate for commodity'). It also distinguishes from sibling tool 'hmrc_search_guidance' by advising verification there for time-sensitive advice.

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 begins with 'USE THIS TOOL WHEN' and specifies the exact condition for use. It also warns against relying solely on this tool for time-sensitive advice and directs to an alternative (hmrc_search_guidance).

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, openWorldHint, idempotentHint, and destructiveHint, so the description's additional mention of searching the GOV.UK API, filtering to HMRC, and returning specific fields adds moderate value but does not significantly expand behavioral understanding beyond 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 very concise with four sentences, each serving a clear purpose: stating when to use, describing output, specifying data source, and giving authoritative guidance. It is front-loaded with the key instruction and contains no redundant or unnecessary information.

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?

The tool has only two parameters, high schema coverage, and an output schema (not shown but mentioned). The description covers purpose, source, output format, and usage context, which is sufficient for an agent to use the tool correctly. It does not address pagination or error handling, but given the simplicity, it is close to complete.

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 the schema already documents both the query and limit parameters. The description adds context about the API source and the nature of the search (HMRC guidance), but does not provide deeper semantics beyond what the schema and parameter descriptions offer.

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 clearly states that the tool searches GOV.UK for HMRC tax guidance, specifies the verb ('search'), the resource (GOV.UK HMRC publications), and provides examples of topics (VAT, income tax, etc.). It distinguishes itself from siblings by focusing specifically on HMRC tax guidance and noting the limitations of general web search.

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 starts with 'USE THIS TOOL WHEN' to indicate appropriate contexts. It also warns against supplementing with web search because it returns out-of-date or third-party information, implying when not to use alternatives. However, it does not explicitly name sibling tools as alternatives, leaving some ambiguity.

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds that the tool is the 'authoritative source for UK judgment metadata,' which adds context about reliability but does not contradict 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 three sentences, each serving a clear purpose: usage trigger, workflow steps, and authoritative note. No wasted words; every sentence earns its place.

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?

The tool has an output schema (not shown but provided), so description does not need to detail return values. It fully covers the metadata fields, workflow integration, and the tool's role in the overall judgment retrieval process, making it complete.

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%, with the slug parameter already described with format examples (e.g., 'uksc/2024/12'). The description does not add new semantic information beyond that, so a baseline of 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 explicitly states the tool's purpose: retrieving judgment metadata (parties, judges, neutral citation, court, dates) given a slug. It clearly distinguishes from sibling tools like judgment_get_index and judgment_get_paragraph by specifying that this tool returns only the header metadata, while others handle paragraphs.

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 provides clear when-to-use guidance ('when you have a judgment slug and need metadata') and outlines a complete workflow: first call case_law_search to get the slug, then use this tool, then judgment_get_index and judgment_get_paragraph for deeper reading. It also notes the tool as an authoritative source.

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, and openWorldHint. The description adds that the tool returns 'eId + preview line for every paragraph', which is behavioral context beyond annotations. No contradictions.

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?

Very concise: three sentences that front-load the purpose, then provide workflow guidance. No filler or wasted words.

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 simple tool with one parameter and an output schema, the description fully covers what the tool does, when to use it, and how to integrate with siblings. No gaps.

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% with a clear description for slug. The tool description doesn't add significant parameter-level detail beyond what the schema already provides, so 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 clearly states 'USE THIS TOOL WHEN you have a judgment slug and want the paragraph navigation index'. It specifies the verb 'get' and resource 'paragraph navigation index', and explicitly distinguishes from siblings like judgment_get_paragraph and case_law_grep_judgment.

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?

Provides explicit usage context: 'Call case_law_search FIRST to get the slug.' Then explains what to do with the results using sibling tools. The description tells the user exactly when to use this tool and how it fits into a workflow.

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, and destructiveHint. The description adds value by specifying the return type (paragraph XML content) and typical token range (400–1,700), which is beyond what annotations provide.

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 concise: two sentences plus a short meta-instruction. It front-loads the purpose and includes only essential information, making it efficient.

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?

Given the existence of an output schema (context indicates true), the description does not need to explain return values. It covers prerequisite steps, alternative methods, and typical token count, making it complete for a retrieval tool.

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 the description adds minimal extra meaning. It mentions eId and slug in context but does not elaborate beyond the schema. 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 clearly states the tool's purpose: to get the full text of a paragraph given a judgment slug and eId. It distinguishes itself from siblings like judgment_get_index and case_law_grep_judgment by specifying prerequisites.

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 gives explicit guidance on when to use this tool (when you have slug and eId) and when to use alternatives (judgment_get_index to discover eIds, case_law_grep_judgment to locate by content). This provides clear context and exclusions.

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?

Discloses content truncation behavior and the presence of 'content_truncated' flag. Adds context about extent, in-force status, and prospective flag beyond annotations (readOnlyHint, etc.). No contradictions.

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?

Well-organized with clear sections: usage condition, return description, important check, and alternative tool. Every sentence adds value without redundancy.

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?

Given the output schema exists, the description appropriately focuses on input, behavior, and key warnings. Covers all necessary aspects for an agent to use the 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?

All 5 parameters are described in the schema (100% coverage). The description provides extra guidance: 'Use the numeric part only' for section, and suggests raising max_chars for long definition sections. Adds value beyond 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?

The description clearly states the tool retrieves parsed text of a specific section from a known Act or SI, with extent and in-force metadata. It distinguishes itself from the sibling tool 'law_read_resource' by offering a structured response versus raw XML.

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?

Explicitly states when to use ('when you have a known Act / SI and want the parsed text...') and provides an alternative for raw XML. Includes a critical warning about checking territorial extent, addressing a common legal research error.

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, and destructiveHint false. Description adds crucial behavioral info: pagination via offset/limit, has_more and total_items fields, example of large statute (Companies Act 2006), and guidance on extracting numeric section identifier. No contradiction with 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?

Description is front-loaded with usage directive, followed by clear explanation of return elements, pagination, and alternative. Five sentences are concise and each adds value with no redundancy.

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?

Given the complexity of pagination and the existence of an output schema (not shown but indicated), the description covers all necessary aspects: what it returns, how to page, how to extract section id, and an alternative tool. Complete for a structured tool.

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?

Input schema has 100% coverage with descriptions for all 5 parameters. Description adds value by explaining pagination parameters (limit, offset) with usage advice ('Raise only when you need a larger slice'), and context for type, year, number. Baseline is 3 but extra context justifies 4.

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 clearly states the tool retrieves the structural table of contents for a known Act or SI, specifying it returns parts, chapters, sections, schedules with XML id and title. It distinguishes itself from sibling tools like legislation_get_section and read_resource by mentioning pagination and structured response.

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?

Explicitly starts with 'USE THIS TOOL WHEN you have a known Act / SI and want the structural table of contents'. Provides an alternative via read_resource for a full TOC without pagination, and specifies when to use this tool (when structured response with offset/limit/has_more is needed).

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 provide readOnlyHint and idempotentHint but the description adds valuable context: explains search behavior (title vs full-text via fulltext parameter), the exact-match nature of filters, and response structure (ranked results with URLs and next_steps hints). No contradictions with 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 appropriately sized with a clear structure: starts with usage instruction, describes output, then details filter discipline, then source. Every sentence adds value without redundancy.

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?

Given the tool's complexity (5 params, output schema exists, sibling tools for chaining), the description covers search behavior, filter pitfalls, chaining workflow, and source authority. It does not need to explain return values because output schema is provided.

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%, but the description adds meaning beyond schema: explains the risk of using type and year filters, the effect of fulltext default vs true, and the purpose of limit. Provides actionable advice for using each parameter effectively.

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 explicitly states the tool's function: 'USE THIS TOOL WHEN searching UK Acts and Statutory Instruments by title, phrase, or full-text.' It clearly identifies the resource (UK legislation) and differentiates from sibling tools like legislation_get_toc and legislation_get_section by indicating a chaining workflow.

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?

Provides explicit guidance on when to use (searching legislation) and when not to use exact-match filters (type, year). Recommends omitting filters when unsure and suggests a workflow: query without year, then read year from results. Also directs chaining to legislation_get_toc and legislation_get_section.

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 readOnly, openWorld, idempotent, non-destructive. Description adds that it returns JSON metadata (name, description, optional arguments), providing useful context beyond 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?

Two sentences, front-loaded with purpose, no unnecessary words. Every sentence adds value.

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?

Simple tool with no parameters and annotations present. Description covers purpose and return format. Output schema likely handles remaining details. Adequate but could mention any ordering or limits.

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?

No parameters exist, so description doesn't need to explain them. Schema coverage is 100%, baseline 3, but description adds value by describing return content, earning a 4.

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?

Clearly states 'List all available prompts' with specific verb and resource. Distinguishes from sibling tools like 'law_get_prompt' and 'dd_list_prompts' by domain (law) and scope (all prompts).

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?

Does not explicitly state when to use this tool vs siblings. Implies it's for listing all prompts, but no guidance on choosing over similar tools like 'law_get_prompt' or 'dd_list_prompts'.

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, openWorldHint, idempotentHint, and no destructive hint. The description adds value by explaining the return format (JSON with metadata) and the distinction between static resources (uri field) and templates (uri_template with placeholders), providing behavioral context beyond the 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 extremely concise (two sentences, three lines) and front-loaded with the main purpose. Every sentence adds value, with no redundant or extraneous information.

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?

Given the existence of an output schema (not shown but indicated), the description is complete enough. It clearly explains what the tool returns and the difference between resources and templates, which is sufficient for a simple listing tool with no parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.