UK Business Tools - Ledgerhall

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

Annotations already declare this as read-only, idempotent, and non-destructive, so the description is not required to repeat that. It adds useful context about the data fields (e.g., insolvency flags) but does not disclose potential edge-case behaviors like missing data or rate limits. This is adequate but not rich 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 two sentences, front-loading the core purpose and then listing returns and usage guidance. Every sentence earns its place with no fluff or repetition of schema/annotation 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?

For a single-parameter read-only lookup, the description provides enough context: it names the data source, lists returned content, and gives the prerequisite workflow. An output schema exists, so detailed return formatting is not needed here.

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 for the single parameter, and the schema description already explains what charity_number is and where it comes from. The tool description adds no further parameter-specific detail beyond the implied meaning of 'charity number', so the baseline 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 the tool 'Fetch the full Charity Commission profile for a charity number', using a specific verb and resource. It also lists the key data returned (trustees, income/expenditure, insolvency flags, etc.), which distinguishes it from sibling tools like dd_charity_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 instructs 'Use charity_search first to find the charity number', which establishes the correct workflow and distinguishes when to use this tool vs. the search tool. This is direct, actionable guidance on usage 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 readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context by explaining that the upstream endpoint returns the full list in one shot and pagination is applied client-side via offset/limit. It also discloses the fields returned (registration number, status, registration date), going beyond annotations without contradicting them.

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 long, with the purpose front-loaded, followed by return fields, a usage alternative, and a pagination note. Every sentence contributes distinct information with no redundancy or filler.

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 a full output schema, annotations, and 100% schema coverage for parameters, the description is remarkably complete. It covers the query scope, return fields, an alternative tool for follow-up, and a non-obvious pagination behavioral trait, leaving no significant gaps for an agent to mis-invoke the 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 needs to add little. It does mention 'offset/limit' in the pagination note, which reinforces the schema but does not provide any additional meaning beyond what the parameter descriptions already offer. 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 with a specific verb and resource: 'Search the Charity Commission register of England and Wales by name or keyword.' It distinguishes itself from the sibling dd_charity_profile by noting that profile is for full details once you 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?

The description explicitly directs users to use dd_charity_profile as an alternative when full details are needed after obtaining the charity number. This provides clear when-to-use guidance and names the alternative tool, satisfying the highest bar for this dimension.

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 meaningful behavioral context beyond annotations: 'Resigned officers are excluded' clarifies data scope, and 'Pagination is handled internally' plus the explicit warning not to pass pagination params discloses important call behavior. This complements the readOnly and idempotent hints 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 compact and front-loaded. The first sentence states the purpose, the second enumerates return content, and the third delivers a critical usage warning. No redundancy or filler.

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 complete schema descriptions, the description need not detail return fields beyond what it gives. It covers purpose, data scope (active vs resigned), and pagination behavior, making it fully adequate for this 1-required-param 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%, so the baseline is 3. The description reinforces that only company_number is meaningful and warns against pagination params, but this adds no new meaning beyond what each parameter's description already states ('Ignored — all officers are returned in one call' and 'Ignored — pagination is handled internally.').

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 'Fetch active officers for a Companies House company number', a specific verb+resource+scope statement. It clearly distinguishes from sibling tools like dd_company_profile or dd_company_psc by focusing on officers and explicitly noting 'active officers' and 'Resigned officers are excluded.'

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 clear context: it requires only company_number, and explicitly warns 'do NOT pass items_per_page or start_index; this tool takes only company_number.' However, it does not name alternative tools for when to use this tool vs. others, so it lacks explicit when-not guidance at the tool-selection level.

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, so the description doesn't need to restate safety. It adds value by disclosing the return fields and the dependency on company_search, offering 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 sentences, front-loaded with the core action, followed by return details and a usage note. Every sentence earns its place; no fluff.

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 one parameter, full schema coverage, and annotations covering safety, the description provides all necessary selection and invocation context. The return contents are explicitly listed, and the prerequisite is covered, so the tool is fully contextualized.

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 covers the company_number parameter 100%, including format and relation to company_search. The description only reiterates 'company number' and the search prerequisite, so it adds little semantic 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 opens with 'Fetch the full Companies House profile for a company number,' which combines a specific verb and resource. It enumerates the profile contents (status, address, SIC codes, compliance flags, charges), clearly differentiating it from siblings like dd_company_officers and dd_company_psc.

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 states 'Use company_search first to find the company number,' establishing a clear prerequisite and workflow context. It doesn't explicitly list alternative tools or when not to use it, so it falls slightly short of full exclusion 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 and destructiveHint=false, but the description adds valuable behavioral context: it details return fields (natures of control, nationality, residence), flags overseas corporate PSC entries as a risk signal, and explains special handling for widely-held PLCs. This goes 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 three sentences, front-loaded with the action, and every sentence adds unique value: what is fetched, what it returns, and special cases. No filler or 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 simplicity (one parameter, output schema present), the description covers all essential aspects: the data returned, the risk-flagging behavior, and the PLC edge case. The presence of an output schema means return-value details need not be enumerated in the description.

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 covers 100% of the single parameter, company_number, with format and example. The description does not add additional parameter semantics beyond this, so the 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 opens with a specific verb-resource pair: 'Fetch Persons with Significant Control (beneficial ownership) for a company.' This clearly identifies the tool's purpose and distinguishes it from sibling tools like company profile or officers, which focus on different corporate 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?

The description provides clear context (use this for PSC data on a company) but does not explicitly mention when not to use it or name alternatives. It implies the scope without giving exclusions, which fits the 'clear context, no exclusions' level.

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, so the safety profile is covered. The description adds useful behavioral context by specifying that results are paginated and listing the returned fields (name, number, status, SIC codes, incorporation date, registered address). This goes beyond the annotations without contradicting them.

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 two sentences long, front-loaded with the primary purpose, and every sentence earns its place. The first sentence states what it does and what it returns; the second provides alternative tool guidance and pagination instructions. There is no filler or repetition.

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 does not need to enumerate return types. It covers the core search purpose, pagination behavior, and directs to company_profile for full records. This is sufficient for an agent to select and invoke the tool correctly in the context of its sibling 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?

Input schema covers 100% of parameters with descriptions. The description adds meaning beyond the schema by explicitly teaching the pagination relationship between start_index and items_per_page. It also re-emphasizes that 'query' is a company name or keyword, reinforcing the schema's semantics.

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 a specific verb and resource: 'Search the Companies House register by company name or keyword.' It clearly differentiates from siblings by advising 'Use company_profile for the full record once you have the company number,' which distinguishes this tool from the related profile tool.

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 alternative guidance: 'Use company_profile for the full record once you have the company number.' It also gives explicit pagination instructions with 'Re-call with start_index=start_index+items_per_page to fetch the next page,' telling the agent how to retrieve additional 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds useful behavioral detail about the return content (reason, Act/section, period, company names), which goes beyond annotations. It doesn't mention auth/rate limits, but those are not critical given the read-only, simple nature.

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 concise sentences: purpose, return details, and usage guidance. Every sentence adds distinct value, and the most important action is front-loaded. No redundant or 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?

For a single-parameter read-only lookup with an output schema, the description covers all essential aspects: what it does, what data it returns, and how to get the required ID. No significant gaps for an agent to select and invoke 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?

The schema provides 100% coverage for officer_id with a clear description (Companies House officer ID, returned by disqualified_search). The description repeats this information without adding new semantic meaning, so it meets the baseline but does not exceed it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches a full disqualification record for a director by officer ID. It distinguishes itself from sibling tools like dd_disqualified_search (which searches) and dd_charity_profile (which handles charities). The verb 'Fetch' and resource are explicit.

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 'Use disqualified_search first to find the officer ID', establishing a clear prerequisite and directing the user to the correct sibling tool. This provides both when-to-use context and an alternative, leaving no ambiguity about the required prior step.

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 safety is covered. The description adds valuable behavioral context: returns specific fields (names, DOBs, disqualification snippets, officer IDs) and the zero-result behavior for company names. This goes beyond annotations, though it does not exhaustively describe pagination edge cases.

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 paragraphs, front-loaded with the core purpose, followed by usage guidance and return-value summary. Every sentence earns its place with no padding or 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?

For a simple search tool with an output schema and comprehensive annotations, the description covers purpose, usage, limitations (company name returns zero), and return fields. It also cross-references a related tool for deeper details, making it contextually 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%, with each parameter well-documented (e.g., query explicitly says 'NOT a company name'). The tool description reinforces the individual-name requirement but does not add substantial new meaning beyond the schema. Therefore 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 opens with a specific verb+resource+scope: 'Check whether a named individual is banned from acting as a UK company director.' This clearly distinguishes the tool from sibling search tools (e.g., company, charity, or property searches) by targeting disqualified directors specifically.

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 guidance is provided: 'Use this tool when asked to check disqualified, banned, or barred directors.' It further states when not to use it: 'NOT a company name, which always returns zero results.' It also points to a complementary tool, disqualified_profile, for full details, effectively differentiating search vs. profile 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, openWorldHint, idempotentHint, and non-destructive. The description adds beyond this by disclosing the routing behavior across different registers and the exact ID format required. This helps the agent understand that one tool serves multiple backends, which is not inferable from annotations 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 two sentences plus a concise bullet list of four route mappings. Every element earns its place: the first sentence states the action, and the list provides essential routing rules in a scannable format. No fluff or 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 that there is a single parameter, a rich output schema, and detailed annotations, the description covers the critical operational nuance—the prefix-based routing—that could otherwise be ambiguous. It is complete for an agent to correctly select and invoke the tool for any of the listed ID types.

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 input schema already fully documents the 'id' parameter with the same format examples. The description's routing list essentially repeats the schema's parameter description, adding no new semantic detail. Thus the baseline of 3 is appropriate since the schema carries the heavy lifting.

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 'Fetch the full record for an ID returned by search' and then details the routing by prefix, which both specifies the action and distinguishes it from the sibling-specific fetchers like dd_company_profile and dd_charity_profile. The explicit list of prefix mappings makes the tool's scope 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?

The description provides clear context for when to use this tool: after a search, with IDs in a specific prefixed format. It does not explicitly state alternatives or exclusions, but the routing list implies which IDs are valid and that this is a unified entry point. It could be stronger by mentioning when to prefer dedicated sibling tools, but it is not misleading.

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 and idempotentHint, so the safety profile is clear. The description adds valuable behavioral context: results are sorted by severity, the Gazette is an official UK public record where publication is legally effective, and the endpoint covers specific notice codes. This goes beyond annotation coverage without contradicting it.

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: the first sentence states the core purpose, then it provides essential details about notice codes, sorting, and follow-up actions. Every sentence adds value, and there is no redundant or filler content. It is slightly longer than two sentences but remains 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 presence of an output schema and annotations, the description is reasonably complete. It explains the legal significance of the Gazette, identifies covered notice codes, describes sorting behavior, and directs users to the notice resource for full wording. Minor gaps exist (e.g., no mention of rate limits or how open-world results might affect completeness), but these are not critical.

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 parameters are already well-documented. The description adds some context around result behavior (severity sorting affecting max_notices) and mention of notice codes, but it mostly restates or complements what is in the schema rather than adding substantial new parameter semantics. 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 opens with a specific verb+resource statement: 'Search The Gazette's insolvency notice index by entity name.' It further clarifies scope by listing corporate notice codes and explicitly distinguishes from the notice resource for full legal wording, making it easy to differentiate from sibling tools like dd_gazette_notice.

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 context for when to use the tool: searching for insolvency notices. It also points to the notice://{notice_numeric_id} resource for reading full legal wording, which suggests an alternative for a related task. However, it does not explicitly state exclusions or compare with other search tools beyond the notice resource.

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=false, covering the safety profile. The description adds useful context about the return format (JSON-LD linked-data record with parties, legal basis, court, full text), going beyond annotation basics. Minor gap: no mention of error conditions or auth, but annotations lower the bar.

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 with the purpose front-loaded. The first sentence states the action, the second describes the return value and prerequisite workflow. 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 tool is simple (one parameter) with rich annotations, an output schema, and a clear workflow instruction. The description covers purpose, return content, and how to obtain the required ID, making it complete for an agent to invoke 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% for the single parameter, and the schema description already explains notice_id as the numeric Gazette notice ID returned by gazette_insolvency. The description's mention of 'numeric notice ID' adds little beyond the schema, so the 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 the tool fetches the full legal wording of a Gazette notice by numeric notice ID, with a specific verb and resource. It distinguishes itself from the sibling gazette_insolvency tool by focusing on full text vs. listing, and mentions the linked-data record 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?

Explicitly instructs to use gazette_insolvency first to find notice_numeric_id values, providing clear workflow guidance and effectively differentiating this tool from its sibling listing tool. This is a direct when-to-use instruction.

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?

With no annotations, the description carries the burden of disclosing behavior. It does disclose the return format ('JSON with a messages array') and how arguments should be structured, but it doesn't mention error handling, permissions, or side effects. Since this is a read-only 'get' operation, the lack of side-effect disclosure is less critical, but more detail would improve transparency.

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 adding essential information: the action, the return type, and the argument format. There is no filler or redundancy, and it is front-loaded with the core purpose.

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 is reasonably complete for this tool's simplicity. It explains the purpose, return structure, and argument format, and the output schema already exists to define return values. It lacks some context about when to use this over listing tools, but that gap is more about usage guidelines. Overall, it is adequate for an AI agent to understand the tool's basic functionality.

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 covers both parameters with 100% description coverage. The description adds meaningful clarity by specifying that arguments should be a dict mapping names to values, which is not explicitly stated in the schema. This goes beyond the schema's simple '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' with a specific verb and resource. It distinguishes itself from siblings like dd_list_prompts by focusing on retrieving a specific prompt rather than listing all prompts. The mention of optional arguments further clarifies the tool's scope.

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 does not provide when-to-use guidance or mention alternatives. It doesn't explain when to use this tool versus dd_list_prompts or law_get_prompt, or any prerequisites or exclusions. The only context is the tool's basic function, which is implied by its purpose.

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 behavioral details beyond the readOnlyHint and idempotentHint annotations, such as the explicit limit of 10 recent transactions, the returned fields, and the automatic postcode extraction from full addresses. It also discloses the England/Wales scope, enriching the agent's understanding of expected 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?

The description is three concise, information-dense sentences that front-load the core purpose, then detail outputs and usage guidance. Every sentence adds value with no redundancy or filler.

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 input format, output contents, geographic scope, and data source, making it self-sufficient for an agent to select and invoke the tool correctly. The presence of an output schema relieves the description from detailing return structure, and annotations cover safety aspects.

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 provides a detailed description of the sole parameter, including examples and reliability notes. The tool description largely repeats this information without adding new semantic meaning, so it does not exceed the baseline for 100% schema description coverage.

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 function with a specific verb ('Search') and a specific resource ('HM Land Registry Price Paid Index'), and distinguishes it from generic property tools by naming the exact dataset and coverage (England and Wales). It also outlines the returned fields, making the purpose 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?

The description provides clear context on how to use the tool, including geographic coverage ('Covers England and Wales only') and reliability tips ('Postcode gives the most reliable results — a full address is also accepted'). However, it does not explicitly mention alternatives or when not to use this tool, which prevents a higher score.

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?

With no annotations, the description carries the full burden. It discloses the return format (JSON) and the metadata fields (name, description, optional arguments). It does not explicitly declare read-only status or pagination, but for a list operation this is mostly sufficient. Minor ambiguity about scope ('all available' vs domain-specific) remains.

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 two sentences, front-loaded with the action, and contains no filler. It efficiently states what the tool does and what it returns.

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 is simple with no parameters and an output schema. The description provides the essential return information. However, the phrase 'all available prompts' is slightly ambiguous regarding domain scope (dd_* vs all prompts), and a brief note about pagination or relationship to law_list_prompts would improve completeness.

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 tool has zero parameters and an empty input schema. The 0-params baseline is 4. The description correctly implies no inputs are required and adds no misleading parameter information.

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 available prompts' with a specific verb and resource. It distinguishes from siblings like dd_get_prompt (single prompt) and law_list_prompts (domain-specific) by saying 'all available' and using the dd_ prefix.

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 usage guidance is provided. The description implies this tool is for discovering available prompts, but it does not contrast with alternatives like dd_get_prompt or law_list_prompts, nor does it state prerequisites 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 readOnly, openWorld, idempotent, and non-destructive behavior. The description goes beyond by explaining matching normalization, false positive/negative risks, partial results when lists are missing, and the meaning of lists_screened and as_at. This adds substantive behavioral context that structured annotations alone do not convey, with 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 structured into focused paragraphs: purpose, matching semantics and caveats, and output field explanations. Every sentence provides essential information for a compliance screening tool. It is front-loaded with the main purpose and does not waste words on repetition.

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 is complex due to compliance implications, but the description thoroughly covers return values (regime, source reference, listing date), data freshness, and partial-result indicators. Even though an output schema exists, the description's explication of lists_screened and as_at is valuable. Combined with the detailed matching caveats, the description is complete for an agent to invoke and interpret results 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 baseline is 3. The description adds extra meaning for the 'name' parameter by explaining normalization (case/accent/punctuation-insensitive) and transliteration pitfalls, which helps users interpret results. It does not add much for 'entity_type', but the existing schema description suffices. Overall, the added matching semantics justify 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?

The description clearly states the tool screens names against UK OFSI, US OFAC, EU, and UN consolidated sanctions lists. This specific verb+resource+scope distinguishes it from all sibling tools, which are general search/profile tools. No ambiguity about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says to use it to check whether a counterparty or associated persons appear on sanctions lists. It also provides critical usage caveats: matching is deterministic, person-name transliteration variants may not match, empty results are not a guarantee, and hits may be false positives. This gives clear when-to-use and when-to-be-cautious guidance, with no competing alternatives in the sibling list.

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=false. The description adds crucial behavioral detail beyond annotations: it returns a list of result IDs (not full records) and searches in parallel across specific registers. This informs the agent that a second fetch call is required, which is essential for correct invocation. Slight gap: no mention of potential pagination or rate limits, but the provided behavior is solid.

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 two sentences long, front-loaded with the core purpose, and each sentence serves a distinct function: what it does and what the output format is. No filler or repetition of schema details, making it efficient and easy 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?

The description fully covers the essential workflow: it searches a known set of registers, returns IDs, and directs the next step (fetch). Given that an output schema exists and annotations indicate read-only behavior, nothing else is needed for an agent to select and invoke the tool correctly. The description is complete for this moderately complex multi-register search.

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?

There is only one parameter, query, and the schema description covers it with 100% clarity ('Company name, charity name, director name, or keyword to search for across all UK due diligence registers'). The tool description adds no additional meaning beyond what the schema already provides. Baseline 3 is appropriate given high schema coverage.

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 uses the specific verb 'Search' and resource 'all UK due diligence registers simultaneously', listing the four named registers. This clearly differentiates the aggregate search from sibling tools like dd_company_search or dd_charity_search which target individual registers. The scope and intent are immediately obvious.

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 that it searches across all registers in parallel and instructs the agent to 'use fetch with each ID to retrieve the full record', providing clear follow-up usage. It does not explicitly mention when not to use this tool or name alternatives, but the context is sufficient for correct selection.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses the return payload (trading name and address) and adds the notable behavioral trait that the trading address often differs from Companies House. It does not mention rate limits or error handling, but the core behavior is transparent.

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 paragraphs: purpose, return value with due diligence note, and exclusion with alternative. Every sentence contributes meaning, 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?

For a single-parameter read-only lookup tool with an output schema, the description covers scope, return content, and alternatives. It lacks nothing essential for an agent to select and invoke 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 description coverage is 100%, so the parameter is fully documented in the schema (formats, normalization, UK-only). The main description adds minimal param-specific detail beyond repeating 'UK numbers only.' The baseline of 3 applies since the schema carries the full burden.

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 a specific verb+resource: 'Validate a UK (GB) VAT number against the HMRC register.' It clearly distinguishes from sibling tools by specifying UK-only scope and the HMRC register, which is different from company search or VAT rate 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?

Explicit guidance is given: 'Non-UK (EU) VAT numbers cannot be validated here — use the EU VIES service for other member states.' It also provides contextual value by explaining the due diligence signal of address discrepancies, which implies when this tool is appropriate.

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 value by specifying the exact return content (title, document type, publication dates, section list) and explicitly what it does not do (return page body), steering users to sibling tools. This is useful behavioral context beyond the annotation flags.

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: purpose, return values, and alternative tools. It is concise, front-loaded with the key verb and resource, and every sentence adds necessary information without 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 the single parameter, informative schema, and existing output schema, the description fully covers what the tool does, what it returns, and how it relates to sibling tools. The agent has enough context to select and invoke it correctly without needing further detail.

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 provides 100% coverage with a clear description and example for base_path. The tool description itself does not add parameter semantics beyond what the schema already provides, so the baseline of 3 for high schema coverage 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 uses a specific verb ('Get') and resource ('GOV.UK page'), and clearly states what is returned (metadata and navigable section index). It explicitly distinguishes from sibling tools by noting that govuk_get_section reads a section body and govuk_grep_content searches within the page.

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 vs alternatives: 'Use govuk_get_section to read the body of a specific section, or govuk_grep_content to search within the page body.' This clearly indicates the tool's scope (metadata/index) and points to alternatives for other use cases.

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 read-only, idempotent, and non-destructive. The description adds a list of returned fields, but an output schema exists, so this is redundant. It provides no additional behavioral context beyond what annotations and schema already convey.

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 two sentences: the first states the core function, the second lists return fields and points to the sibling for slug discovery. Every sentence earns its place; no fluff.

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 one-parameter, read-only tool with both input and output schemas, the description is complete. It covers what the tool does, what it returns, and how to obtain valid input (slugs). No significant gaps remain.

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 parameter description already includes an example ('hm-revenue-customs') and a pointer to govuk_list_organisations for finding slugs. The tool description's mention of 'slug' and 'discover slugs' merely repeats schema content, adding no new 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 states a specific verb ('Get') and resource ('profile of a UK government organisation by its slug'), immediately distinguishing it from list-style siblings like govuk_list_organisations. It also lists return fields, making the tool's function unmistakable.

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 for browsing/discovering slugs, which tells the agent when NOT to use this tool. This clear alternative makes the usage context unambiguous.

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, destructiveHint=false, so the safety profile is known. The description adds little beyond that—it confirms the read operation and the dependency on govuk_get_content, but does not describe return format, pagination, or error behavior. With annotations covering mutation risks, a score of 3 is appropriate.

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 with no wasted words. The purpose is front-loaded, and the usage note is directly actionable. 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?

For a simple two-parameter read tool with rich annotations and an output schema, the description fully captures the workflow: get anchors first, then fetch a section. No additional context is needed for an agent to invoke 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% with both parameters fully described. The description reinforces the role of 'anchor' but adds no new semantic detail beyond what the schema already provides. Baseline 3 is correct when schema does the heavy lifting.

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', specifying the exact resource and scope. It distinguishes from siblings by emphasizing 'one named section', and the usage note explicitly references govuk_get_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?

Explicit sequential guidance: 'Use govuk_get_content first to get the list of available section anchors, then call this with the anchor'. This names the alternative tool and provides clear when-to-use context, leaving no ambiguity about the required prerequisite.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe read operation. The description adds valuable behavioral context beyond annotations: the return format ('{anchor, heading, snippet, match} hits') and the regex fallback behavior ('if it doesn't compile, falls back to literal substring'), which are not inferable from annotations 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 compact and front-loaded: the first sentence states the core purpose, the second explains the return format and when to use, and the third covers the regex fallback. Every sentence earns its place with no filler or repetition of schema details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only search tool with an output schema, the description covers purpose, return format, usage guidance, fallback behavior, and relationship to sibling tools (govuk_get_section). No critical information is missing for an agent to select and invoke 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 description coverage is 100%, so parameter descriptions already explain each field thoroughly. The description adds marginal value by explaining the fallback from regex to literal substring, which is partially reflected in the schema's 'Regex or literal substring' wording, but it doesn't provide significant additional semantic detail 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 begins with a specific verb+resource+scope: 'Find body sections in a GOV.UK content item matching a pattern.' It also distinguishes itself from sibling tools by explicitly noting this is for content-based questions 'rather than navigating by section number,' referencing govuk_get_section as the alternative.

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: 'Use this when answering content-based questions... rather than navigating by section number' and explains that the returned snippets help the LLM decide 'which full sections to read via govuk_get_section.' This clearly states when to use and names the alternative 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context about pagination ('Returns a paginated list') and the specific fields returned (slug, acronym, type, status), which goes 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 two sentences, front-loaded with the primary action, and every sentence adds value—no fluff or 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?

For a simple pagination tool with full schema coverage, output schema present, and strong annotations, the description is complete. It covers purpose, return content, pagination, and usage guidance.

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%, with both 'page' and 'per_page' clearly described. The description does not add extra parameter meaning beyond the schema, so a baseline score 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 starts with 'List all UK government organisations registered on GOV.UK', which is a specific verb+resource combination. It also distinguishes itself from siblings by noting it helps 'discover slugs for use with govuk_get_organisation or govuk_search filters'.

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 it: 'Use this to browse the full government structure or discover slugs for use with govuk_get_organisation or govuk_search filters.' This names specific alternative tools and clarifies the use case.

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 valuable context beyond annotations by disclosing the external API dependency: 'Uses the postcodes.io public API (no key required).' This informs the agent about network reliance and lack of authentication requirements, exceeding the baseline for annotated tools.

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 compact and front-loaded: the first sentence states the core purpose, the second gives use cases, the third provides an implementation detail. Every sentence contributes original value with no repetition of schema or annotations.

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, read-only lookup with one parameter, an output schema, and comprehensive annotations, the description fully covers the essentials: what it does, when to use it, what it returns, and external API details. No critical gaps remain.

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%, including a descriptive example and length constraints. The description itself only refers to 'UK postcode' without adding new parameter syntax or format details. Baseline 3 is appropriate; the schema carries the semantic weight.

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 function: 'Look up a UK postcode to retrieve its local authority, region, constituency, and other administrative geography.' This specific verb+resource+output combination unambiguously distinguishes it from all sibling tools, none of which perform postcode lookups.

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 strong usage context: 'Useful for determining which council area, parliamentary constituency, or NHS region a postcode falls within. Commonly used to direct users to the correct local service on GOV.UK.' While it does not explicitly mention alternatives or when-not-to-use, the context makes the intended use clear, and no sibling tools offer postcode lookup.

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, covering the safety profile. The description adds beneficial context (returns list with specific fields, official API) but does not disclose rate limits, authentication needs, or pagination behavior beyond the schema's start parameter. 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 three concise sentences: first states purpose and source, second summarizes return fields, third gives filtering guidance. Every sentence earns its place, and the key verb 'Search' is 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 output schema and annotations, the description sufficiently covers purpose, return shape, and filter usage. It lacks explicit guidance on when to use this tool versus sibling tools, but that is addressed in the usage dimension and does not significantly hinder completeness 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 description coverage is 100%, so baseline is 3. The description enriches parameter semantics by providing concrete examples for filter_format (transaction, guide, publication) and filter_organisations (with departmental slugs), which is not present 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 the action (search), resource (GOV.UK content items), and method (official Search API). It also distinguishes itself from siblings like gov_govuk_get_content (retrieval of specific items) and gov_govuk_grep_content (grep-style search) by emphasizing the API-based search over the broader content set.

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 usage context, noting how to narrow with filter_format and filter_organisations, including practical examples for content types. It does not explicitly name alternative tools or exclusion criteria, so it stops short of a 5.

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, and non-destructive. The description adds important behavioral context: summary text is capped per max_summary_chars and users should 'check summary_truncated in the response.' It also specifies the Royal Assent field is included 'if enacted,' clarifying conditional data presence.

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 tightly organized into three purposeful sections: when to use, what it returns, and next steps. Every sentence provides actionable information with no filler or 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 simplicity (2 params, output schema present), the description fully covers usage context, return contents, truncation behavior, and downstream actions. No gap in understanding remains for the agent to invoke 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 description coverage is 100% and parameter descriptions are already detailed (e.g., bill_id source, max_summary_chars default/range/truncation). The tool description reinforces that max_summary_chars caps summary length but adds no new semantic info 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 opens with 'USE THIS TOOL WHEN you have a bill_id (from bills_search_bills) and want the full detail,' which clearly states the verb (get), resource (bill detail), and prerequisite source of the ID. It further lists specific returned fields (sponsors, current stage, long title, summary, Royal Assent date), distinguishing it from the sibling search tool.

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 'USE THIS TOOL WHEN' identifies the exact condition for use. It also provides post-call guidance: 'AFTER calling, use parliament_search_hansard... or bills_search_bills... for adjacent bills,' effectively indicating alternatives and when not to use this tool (when seeking debates or related bills).

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, but the description adds behavioral context by mentioning pagination ('paginated page of bill summaries') and the nature of the returned data. It also gives a clear follow-up action, which is useful 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 four sentences, each serving a distinct purpose: when to use, what it returns, what to do next, and why to trust it. The 'USE THIS TOOL WHEN' prefix is a clear and efficient trigger. No superfluous 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?

The description covers the core functionality, pagination, and a clear pointer to a complementary tool for deeper details. With an output schema present, it does not need to enumerate return fields. The tool is a straightforward search operation, and this description fully equips the agent to invoke 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?

The schema covers 100% of parameters with detailed descriptions, so the description does not need to add much. It does mention the filter dimensions (keyword, session, house, stage) that correspond to parameters, but this adds little beyond the schema. Baseline 3 is appropriate given the high schema coverage.

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 function: searching UK parliamentary bills by keyword, session, house, or legislative stage. It also distinguishes itself from the sibling tool law_bills_get_bill by explicitly directing users to use that tool for full detail after this 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 opens with 'USE THIS TOOL WHEN searching UK parliamentary bills...' which explicitly states when to use it. It also provides guidance on when to use an alternative: 'AFTER calling, pass a bill_id into bills_get_bill for full detail' and notes that it is the authoritative source for bill status.

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?

Adds value beyond the annotations (readOnlyHint, idempotentHint) by disclosing the exact return shape ({eId, snippet, match}), the 'small per-paragraph snippets' behavior, and the regex fallback to literal substring matching. 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?

Well-structured and front-loaded with the trigger condition. Every sentence adds value: return format, use case, alternatives, and regex behavior. No fluff or repetition.

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 an existing output schema, the description covers the key usage scenario, distinguishes from related tools, explains the regex behavior, and points to the next step for reading full paragraphs. This is complete and self-sufficient.

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 each parameter is already described. The description reinforces that 'pattern' is regex with fallback, but does not add new parameter-specific syntax or constraints beyond the schema. Baseline 3 is appropriate when schema carries the param load.

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 a specific verb+resource combo: 'find paragraphs whose text matches a pattern' within a UK Court Judgment. It clearly distinguishes from sibling tools like judgment_get_index and judgment_get_paragraph, and from broader search 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?

Explicit when-to-use statement ('USE THIS TOOL WHEN you have a judgment slug...'), a concrete use case, and direct alternatives: 'For paragraph-number navigation by eId, call judgment_get_index instead.' Also explains the follow-up step to read full paragraphs.

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?

Goes well beyond the readOnlyHint/idempotentHint annotations by disclosing upstream filter issues (from_date/to_date silently ignored), judge parameter quirks (honorific suffixes zero results), and pagination slicing behavior. The description also clarifies coverage limitations ('from roughly the early 2000s onwards') and TNA's stability as an authoritative source.

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 long but every sentence earns its place by conveying a distinct operational fact or guidance. It is front-loaded with the primary directive, then structures follow-up actions, narrowing strategies, coverage caveats, and authority endorsement. No redundancy detected.

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 8 parameters and rich sibling ecosystem, the description covers all essential context: return payload, downstream workflow, filter pitfalls, coverage scope, and comparison with non-specialized search. The presence of an output schema does not reduce the need for this descriptive completeness, and the description delivers fully.

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?

Although schema coverage is 100%, the description adds crucial parameter-level semantics: it warns that judge suffix forms fail, demonstrates correct usage ('Reed' or 'Lord Reed'), explains limit slicing client-side, and advises refinement strategy for date filters. This significantly exceeds schema baseline.

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 a clear directive: 'USE THIS TOOL WHEN searching UK case law by party names, court, judge, date, or free-text query.' It identifies the specific resource (UK case law) and differentiates from sibling tools by listing what to do after calling (e.g., judgment_get_header, citations_resolve). No ambiguity about tool purpose.

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 the tool and provides alternatives: 'use case_law_grep_judgment to find text within a single judgment' and 'pass the neutral citation into citations_resolve.' It also warns against using web search and describes fallback strategy for older authorities. This is exemplary usage 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 establish readOnly and non-destructive behavior, so the description adds critical behavioral context: refusal conditions (confidence 0.0, missing resolved_url), the 'no network call' property, and the strong prohibition against constructing inputs manually to prevent citation fabrication. 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?

Although somewhat long, every sentence delivers essential operational guidance: ordering, input provenance, refusal triggers, and anti-fabrication policy. The bold 'USE THIS TOOL AFTER' and 'DO NOT construct' warnings are prominent, and the text is well-structured 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?

The description covers the full invocation context: pipeline position, input requirements, failure modes, and authoritative formatting behavior. With an output schema present, return-value details are unnecessary. The tool's high-stakes nature (citation fabrication) justifies the thorough guidance.

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 each parameter described as coming from citations_resolve, so the schema carries the parameter details. The description enhances this by mandating that fields must be passed directly from citations_resolve and never guessed, adding provenance semantics that reduce fabrication risk.

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: 'produce the correctly formatted OSCOLA citation string' and 'Formats per OSCOLA 4th edition rules for each citation type.' It also distinguishes itself from sibling tools by explicitly saying 'USE THIS TOOL AFTER citations_resolve,' positioning it as the formatting step in a two-tool 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?

The description gives explicit when-to-use guidance: 'USE THIS TOOL AFTER citations_resolve' and instructs to pass parsed fields directly. It also provides exclusions: refuses when confidence is 0.0 or when neutral citations lack a resolved_url, and tells the agent to surface the failure rather than fabricate a citation.

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 concrete behavioral details: it fetches the judgment XML from TNA, parses OSCOLA citations, and returns grouped, deduplicated, and sorted results. This significantly extends transparency 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 well-structured and concise: an upfront usage trigger, a brief process explanation, a follow-up instruction, and two high-level use cases. Every sentence earns its place, and the content 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 tool has a single parameter, a detailed schema, an output schema, and helpful annotations, the description fully covers input, process, follow-up, and use cases. It leaves no significant gaps for an agent to select and invoke 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?

The schema provides 100% coverage for the single parameter case_uri, including format, examples, and a prefix exclusion instruction. The description only uses the synonymous term 'judgment slug' and does not add new semantic information beyond the schema's rich definition, so the baseline score 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 the tool maps every citation a judgment makes, enumerating categories such as cases, legislation, SIs, and retained EU law. It is distinguished from siblings like law_citations_parse by focusing on the citation network extracted from a judgment's XML, with a specific verb+resource.

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 opens with 'USE THIS TOOL WHEN you have a judgment slug and want to map every citation,' which is an explicit usage condition. It also tells the agent to pass individual citations through citations_resolve afterward, providing clear follow-up guidance and alternative interaction via a sibling 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?

Beyond the readOnlyHint=true annotation, the description discloses important behaviors: pure-regex default, optional MCP sampling for disambiguation with implications (model shapes result), URL resolution to TNA/legislation.gov.uk, and the important limitation that the parser recognizes shape but does not confirm existence. The description also mentions it connects to the client's model, which is beyond the annotation.

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 clear sections (use case, supported types, behavior, follow-up). It is longer than average but every sentence adds relevant information. The 'USE THIS TOOL WHEN' directive is front-loaded. Minor redundancy with schema description keeps it from a 5.

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, the description needn't explain return values. It covers input requirements, parsing behavior, optional disambiguation, URL resolution, and a recommended follow-up action. The combination of annotations, schema, and description leaves no significant gaps for an agent to use 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% for both parameters (text and disambiguate). The description does restate some parameter context (e.g., disambiguate triggers MCP sampling), but it does not add meaning beyond what the detailed parameter descriptions already provide. Baseline 3 is appropriate because the schema carries the full burden.

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-style citations from free text. It explicitly lists supported citation types (neutral citations, law reports, legislation sections, SIs, retained EU law), which distinguishes it from sibling tools like law_citations_format_oscola and law_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?

The description opens with 'USE THIS TOOL WHEN you have free text...' establishing the exact trigger scenario. It also provides explicit post-condition guidance: 'AFTER calling, pass each citation through citations_resolve to verify' — this gives the agent a clear workflow and indirectly distinguishes this tool from the resolve 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?

With annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, the description adds substantial context: live TNA HEAD check, confidence set to 0.0 on non-200, transient error retry behavior, and the instruction to surface failures rather than fabricate citations. This far exceeds the annotation baseline and provides critical operational details.

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 about 180 words but every sentence delivers essential information: primary use, behavior, failure modes, and critical cautions. It is front-loaded with a prominent uppercase usage directive and structured with clear paragraphs. No filler or redundancy; it earns its length for a tool with network-dependent behavior.

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 covering return values, so the description focuses on behaviors, errors, retries, confidence semantics, and anti-fabrication rules. It covers failure modes (timeout, connection error), retry policy, and user guidance on what to do if resolution fails. Given the complexity of live TNA checks and confidence scores, this is admirably complete without needing further elaboration.

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 input schema with explicit examples and length constraints, achieving 100% schema coverage. The description mentions citation types (neutral citation, SI, legislation section, retained EU law) which overlaps with the schema but does not add additional parameter-level syntax or format details. Schema carries the burden, so 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?

The description uses a specific verb ('Parses + resolves') and resource ('a single citation') and immediately distinguishes itself by explaining the use case: 'USE THIS TOOL BEFORE constructing an OSCOLA citation string from known fields, OR to confirm a citation points at a real document.' This clearly differentiates it from siblings like law_citations_parse and law_citations_format_oscola.

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 ('USE THIS TOOL BEFORE constructing...') and strong when-not-to-use warnings ('Do NOT format or quote a confidence-0.0 citation', 'do NOT manufacture a citation'). However, it does not explicitly name sibling alternatives, only implies that formatting from known fields is a different route. This is clear and actionable but stops short of named alternatives, so a 4 is appropriate.

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 covered. The description adds valuable behavioral context beyond annotations by disclosing that the tool fetches committee detail AND member list in parallel, setting expectations for response composition. No contradiction exists.

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, each earning its place: the first front-loads the trigger condition, the second states the action, and the third provides actionable next-step guidance. The ALL-CAPS emphasis on 'USE THIS TOOL WHEN' and 'AFTER calling' highlights the most decision-relevant text. No fluff or repetition.

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?

This is a simple single-parameter tool with full annotation coverage and an output schema, so the description need not explain return values. It covers what the tool does, when to use it, and the next step in the workflow, which is complete guidance for an agent to select and invoke 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%; the schema already documents committee_id as coming from committees_search_committees results. The description reinforces this source and shows the parameter's role in the follow-up workflow, but it does not add significant new meaning 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 states a specific verb+resource: 'Fetches committee detail and member list in parallel.' The trigger condition 'when you have a committee_id' clearly distinguishes this from sibling search tools like law_committees_search_committees, and the mention of 'metadata + current membership' defines the exact scope.

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 opens with an explicit when-to-use directive ('USE THIS TOOL WHEN you have a committee_id'), and it names a related alternative ('pass committee_id into committees_search_evidence') with a clear workflow instruction. The when-not-to-use is strongly implied by the conditional phrasing, making this a model of usage 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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: it returns 'committee summaries (name, house, active status, ID)' and explicitly describes the follow-up actions, which tells the agent what to expect from the output and how to chain tools. This goes beyond the annotations without contradicting them.

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. The first line is a clear imperative ('USE THIS TOOL WHEN...'), immediately followed by the return summary and downstream steps. Every sentence earns its place: purpose, output, and usage flow. No fluff or repetition of schema details.

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 that an output schema exists (so return values are already structured) and annotations cover safety and idempotence, the description provides sufficient context for decision-making. It explains what the tool does, what it returns, and how to proceed with the results. It does not cover edge cases like empty results or error behavior, but these are not critical for a simple read-only search tool; the overall guidance is complete enough.

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%—all four parameters (house, limit, query, active_only) have detailed descriptions with defaults, bounds, and examples in the schema itself. The tool description does not add additional parameter-level meaning; it only mentions 'name, house, or active status' in the purpose, which maps to existing schema fields. Per the rubric, a baseline of 3 is appropriate when the schema does the heavy lifting.

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: 'searching or listing UK parliamentary select committees by name, house, or active status.' It names the specific resource (UK parliamentary select committees), the actions (searching/listing), and the filtering dimensions. It also distinguishes itself from sibling tools by directing the user to pass committee_id to committees_get_committee or committees_search_evidence afterward, thereby clarifying its unique role 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?

The description opens with 'USE THIS TOOL WHEN searching or listing...' which is an explicit when-to-use directive. It also provides downstream usage guidance ('AFTER calling, pass committee_id into...'), which helps the agent choose the next tool. However, it does not explicitly state when NOT to use this tool or name direct alternatives for the same search task, which would elevate it to a 5.

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 useful behavioral context beyond this: pagination behavior ('Returns ONE PAGE of evidence'), caps on title lengths and witness lists, and the authoritative-source note. 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 three sentences, front-loaded with the use condition, and every sentence carries meaningful information (when to use, pagination, caps, authority). No filler or 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?

For a paginated list tool with a 100% schema coverage and an output schema present, the description covers the essential operational details: pagination, per-item caps, and the authoritative nature of the source. It does not need to describe return values since an output schema exists.

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%, with detailed parameter descriptions (e.g., limit split across oral/written, offset behavior, max_title_chars intent). The description itself adds minimal parameter-specific information beyond the schema, so the 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 opens with an explicit, conditional imperative: 'USE THIS TOOL WHEN you have a committee_id and want the oral and written evidence submitted to it.' This clearly identifies the verb (search), resource (committee evidence), and scope (oral/written), and distinguishes it from siblings like law_committees_search_committees and law_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?

It explicitly states the condition for use (having a committee_id) and provides concrete pagination guidance ('re-call with offset=offset+returned while has_more is true'). It does not explicitly name alternatives or when-not-to-use scenarios, but the intended use case is unambiguous and actionable.

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 behavior. The description adds useful behavioral context by stating that it returns a rendered prompt as JSON with a messages array and that arguments should be a dict mapping names to values, which goes beyond the annotations without contradicting them.

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 two sentences long, front-loaded with the core action, and contains no filler. Every sentence provides value: the first states the purpose, the second clarifies output and argument format. Excellent 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 tool's simplicity, strong annotations, and the presence of an output schema, the description sufficiently covers the key behavioral aspects: what it does, how arguments are passed, and the output shape. No critical information is missing for an agent to select and invoke 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% for both parameters, so the schema already documents each parameter. The description reinforces the arguments format ('dict mapping argument names to values') but adds little beyond what the schema provides. 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 'Get a prompt by name' with a specific verb and resource, making the core purpose unambiguous. However, it does not explicitly differentiate itself from sibling tools like 'law_list_prompts' or the similarly named 'dd_get_prompt', so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage: use this tool when you have a prompt name and want the rendered prompt. There is no explicit mention of alternatives or when not to use it, such as pointing to 'law_list_prompts' for discovery, so guidance is only implied.

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?

Beyond the read-only and idempotent hints in annotations, the description adds crucial operational context: the default to HMRC sandbox, the production URL via HMRC_API_BASE, and the need for HMRC_CLIENT_ID/SECRET credentials. It also discloses that the tool raises an error if credentials are missing, and explicitly warns not to infer status. This is exactly the kind of behavioral detail that annotations don't capture.

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 front-loaded, with the most important 'when to use' statement first. It covers purpose, return values, and setup in just a few lines 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?

For a simple one-parameter read-only tool with an output schema and annotations, this description covers all essential aspects: trigger condition, return fields, environment configuration, and error behavior. The existence of an output schema means detailed return-value structure need not be in the description.

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 description mentions the VRN and its format in the trigger sentence, but the schema itself already provides full coverage with min/max lengths, an example, and the note about GB prefix stripping. No additional parameter meaning is added beyond the schema, so the baseline score for high coverage 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 opens with an explicit trigger: 'USE THIS TOOL WHEN you have a 9-digit VAT Registration Number and need that business's Making Tax Digital VAT mandate status.' This clearly specifies the verb (check), the resource (MTD VAT status), and the starting condition. It distinguishes from sibling VAT tools such as law_hmrc_get_vat_rate which handles rates, not mandate status.

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 tool is explicitly scoped to a scenario involving a VRN and the MTD mandate status. It also states environment and credential prerequisites, implying that this tool is not usable without proper configuration. However, it doesn't explicitly name alternate tools to use instead in other scenarios, so it falls just short of full 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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses that the data comes from a static lookup table current as of 22 Nov 2023, that rates may have changed, and that results include effective date and conditions. This adds valuable behavioral context about data freshness and scope.

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: a usage directive, a clear statement of return value, and an important caveat about static data with an alternative. Every sentence adds meaningful information without redundancy, and it is front-loaded with the primary use case.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with an output schema, the description sufficiently covers the core purpose, return expectations, and a critical limitation (static data). It also points to an alternative for verification, making it complete for the tool's complexity and 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?

The input schema already provides 100% coverage for the single parameter (commodity_code) with a detailed description and examples. The tool description adds only the 'UK' qualifier and switches 'code' to 'description,' which is minimal additional semantic value. The baseline of 3 is appropriate when the schema does the heavy lifting.

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 function: to get the VAT rate category for a UK commodity or service, with a specific verb ('get') and resource ('VAT rate'). It distinguishes itself from sibling tools by focusing on VAT rate lookup and explicitly mentions the return fields (rate, effective date, conditions).

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 you have a UK commodity or service description and want its VAT rate category,' providing a clear usage condition. It also names an alternative tool (hmrc_search_guidance) for time-sensitive advice, thus offering both when-to-use and when-not-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, idempotentHint, and destructiveHint, so the description only needs to add context. It adds the return values (titles, URLs, summaries, last-updated dates) and specifies the source (official GOV.UK content API), which goes beyond the annotations. It does not mention rate limits or authentication, but for a read-only search this is adequate.

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 four sentences long, front-loaded with the usage directive, and contains no fluff. Each sentence serves a distinct purpose: when to use, what it returns, where it searches, and why it's authoritative. It is exceptionally concise 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?

With an output schema present and only two parameters (one required), the description provides sufficient context: the purpose, the data source, the return fields, and a warning about alternatives. It is fully adequate for an agent to select and invoke 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 coverage is 100% with detailed descriptions for both query and limit parameters. The description does not add any parameter-specific semantics beyond what the schema already provides. Baseline 3 is appropriate because the schema carries the full burden.

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 identifies the tool's function: searching GOV.UK for HMRC tax guidance. It specifies the verb 'search', the resource 'HMRC tax guidance', and the scope (GOV.UK content API filtered to HMRC publications), distinguishing it from sibling tools like gov_govuk_search and other HMRC-specific 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 explicitly says 'USE THIS TOOL WHEN searching GOV.UK for HMRC tax guidance' and warns against web search with 'do not supplement', providing clear when-not guidance. However, it does not name sibling tools as explicit alternatives, so it falls just short of a perfect 5.

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, setting the safety baseline. The description adds value by labeling the tool an 'Authoritative source for UK judgment metadata,' providing data reliability context beyond the schema. It doesn't 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 long, with the most important usage instruction front-loaded in the first sentence. Every sentence serves a purpose—purpose, workflow, and authority—with no redundant or irrelevant 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?

For a simple one-parameter tool with an output schema and strong annotations, the description fully covers when to use it, how to obtain the slug, and how it fits into a larger workflow. It leaves no significant gaps for the agent to resolve.

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%, with the parameter 'slug' fully described and examples provided. The description only references 'judgment slug' without adding new format or syntax details, so it adds minimal value beyond the schema, warranting the baseline score of 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 function: retrieving judgment metadata (parties, judges, neutral citation, court, dates) given a slug. It distinguishes from sibling tools like judgment_get_index (paragraphs) and judgment_get_paragraph (individual paragraphs) by specifying the metadata focus.

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 'USE THIS TOOL WHEN' statement provides a clear precondition (having a slug) and the need for metadata. It also outlines the workflow: call case_law_search first to get the slug, then judgment_get_index, then judgment_get_paragraph, which guides the agent on sequencing and when alternatives are appropriate.

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?

With annotations already declaring readOnlyHint, idempotentHint, and destructiveHint=false, the description adds useful behavioral context by specifying that the output contains eId and preview line per paragraph. It also clues the agent that this is a list/index operation rather than full-text retrieval, which supports correct follow-up tool selection.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the primary purpose and keeps all sentences purposeful. It packs workflow, tool interrelationships, and output expectations into three concise lines without unnecessary filler.

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 is simple, has one fully documented parameter, includes an output schema, and benefits from complete annotation coverage. The description supplies the necessary contextual glue by linking to preceding and follow-up tools, making it sufficiently complete for accurate agent invocation.

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 covers the single parameter with a clear example ('uksc/2024/12'), and the description reinforces the meaning by saying the tool is used when you have a judgment slug and instructs you to get it from case_law_search. This adds practical guidance beyond the schema's bare definition.

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 returns a paragraph navigation index with 'eId + preview line for every paragraph.' It names the specific resource (judgment paragraphs) and distinguishes itself from sibling tools like case_law_search, judgment_get_paragraph, and case_law_grep_judgment by positioning it as the index lookup 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?

The description begins with 'USE THIS TOOL WHEN you have a judgment slug,' providing an explicit trigger condition. It also prescribes the workflow: call case_law_search first to obtain the slug, then use this tool, and afterward feed eIds into judgment_get_paragraph or case_law_grep_judgment, thereby clarifying when to use this tool versus its 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 behavior. The description adds value by disclosing the return type (paragraph XML content) and typical token range (400–1,700 tokens), which is not present in 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, front-loaded with the triggering condition, and no unnecessary words. Each 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 availability of an output schema and comprehensive annotations, the description covers prerequisites (get_index first), alternatives (grep), return format, and expected size. It is complete for the tool's complexity.

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% with detailed parameter descriptions and examples, including normalization of numeric eIds. The description adds minimal extra semantic value beyond the schema, 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 opens with 'USE THIS TOOL WHEN' and specifies the exact scope: full text of a paragraph given a judgment slug and LegalDocML eId. This clearly distinguishes it from sibling tools like law_judgment_get_index and law_judgment_get_header.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly instructs to call judgment_get_index FIRST to discover eIds and mentions case_law_grep_judgment as an alternative for locating paragraphs by content. This provides clear when-to-use and alternative 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?

The description discloses significant behavioral traits beyond annotations: content truncation via max_chars, the need to check content_truncated, and the warning about extent applicability. These are not visible from the readOnlyHint/idempotentHint annotations, and the description proactively warns about a common legal-research error. 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 an immediate use-case directive, followed by return-value details, truncation warning, extent caution, and an alternative. Every sentence serves a purpose; the content is dense yet readable, and the key usage instruction is 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 output schema exists, the description does not need to enumerate all return fields, but it covers the essential return components (text, extent, in-force status, prospective flag), the truncation mechanism, and the alternative tool. It is complete for a moderately complex tool with 5 parameters and rich annotations.

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 baseline is 3. The description adds value by explaining the max_chars parameter's practical use (raising for long definition sections, checking content_truncated) and clarifying the default token estimate. It does not describe the path parameters, but the schema already does this comprehensively.

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: retrieving parsed text of a specific legislation section with extent and in-force metadata. It distinguishes itself from law_read_resource by explicitly positioning this tool as the parsed structured response alternative to raw XML, which also differentiates it from sibling tools like law_legislation_get_toc.

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 ('USE THIS TOOL WHEN you have a known Act / SI and want the parsed text of a specific section') and provides a named alternative (read_resource for raw CLML XML). It also includes a critical usage reminder to check extent, which adds practical guidance beyond simple triggering.

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 cover read-only/idempotent safety, but the description adds concrete behavior: the return format ('XML id and title'), pagination semantics with offset/limit and has_more/total_items, and the specific example of Companies Act 2006. It also clarifies the id format ('section-47' vs '47'), which is valuable 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?

Four neatly separated paragraphs front-load the core purpose, then add return details, pagination guidance, and an alternative. Every sentence carries meaningful information; there is no filler or repetition, making it appropriately sized for a tool with 5 parameters.

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, return values need no further explanation. The description covers key operational aspects: pagination with has_more/total_items, the alternative read_resource path, and chaining to legislation_get_section. This is comprehensive for a TOC 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 coverage is 100%, so the baseline is 3. The description supplements by explaining how offset/limit paginate through large statutes, and that the type code comes from legislation_search results. While not essential given the rich schema descriptions, it adds practical usage context without redundancy.

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 you have a known Act / SI and want the structural table of contents', clearly specifying the action (get TOC) and resource (known Act/SI). It distinguishes from the sibling tool law_legislation_get_section and the alternative via read_resource, making its unique purpose unmistakable.

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 provides a direct alternative (read_resource) with a comparison of structured vs. string output. Also instructs the agent to pass the numeric section identifier to legislation_get_section after calling, giving clear next steps 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?

Annotations already declare readOnly/idempotent/destructive=false, and the description adds non-obvious behaviors: ranked results with next_steps hints, and the warning that guessing a year will zero out results. It also clarifies the `fulltext` switch from title-only to full-text search.

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 compact yet dense, front-loaded with the use case in caps. Each paragraph addresses a distinct aspect: scope, returns/workflow, filter discipline, and source authority—no filler.

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?

Combined with the detailed input schema and output schema, the description fully covers: what to search, how to filter safely, what results look like, and how to drill into sections. No important aspects of searching UK legislation are left unexplained.

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 100% of params, but description adds strategic parameter usage beyond schema: exact-match semantics for `type`/`year` and the advice to omit them when unsure. It gives concrete examples for `fulltext` (e.g., 'rental deposits').

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 Acts and Statutory Instruments by title, phrase, or full-text,' which names the specific verb and resource scope. It distinguishes from sibling tools like law_case_law_search by explicitly limiting to UK Acts and SIs on legislation.gov.uk.

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 provides clear 'when to use' instructions and filter discipline, including exact-match warnings for `type` and `year`, and when to omit them. It also names the chaining workflow to legislation_get_toc and legislation_get_section, giving explicit alternatives for structural drill-in.

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