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?

The annotations already declare readOnly, openWorld, and idempotent hints, and the description adds valuable behavior beyond them: the upstream endpoint returns the full list in one shot with client-side pagination, and a no-match query is a successful empty array rather than an error because an upstream 404 is translated to 'charities: []'. This prevents an agent from misinterpreting normal empty results.

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, front-loaded with the core purpose, and every sentence earns its place: purpose/return fields, routing to charity_profile, pagination behavior, and empty-result handling. There is 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 tool's modest complexity, complete parameter schemas, rich annotations, and an output schema, the description covers everything an agent needs to invoke it correctly: what it searches, what it returns, how pagination works, and how no-match results are signalled.

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 input schema fully documents query, limit, and offset. The description reinforces that query is a name or keyword but does not add meaningful semantic detail 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 action ('Search the Charity Commission register of England and Wales') and names the returned fields: registration number, status, and registration date. It also distinguishes itself from the sibling charity profile tool by saying to use charity_profile for full details once a charity number is known.

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 clearly signals when to use this tool: to search the charity register by name or keyword. It also provides an explicit routing instruction to charity_profile for full detail. It does not enumerate exclusions or contrast with generic search siblings, but the context is clear enough for an agent.

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

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

The description goes beyond the readOnly/openWorld/idempotent annotations by disclosing important behavior: how satisfaction is represented (not a separate 'release' record), which flags and particulars are included, and the relationship to company_profile.has_charges. This provides valuable interpretive context for an AI agent using the data.

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 primary action, but it includes a few explanatory clauses that could be slightly tightened. Overall, each major piece (scope, return contents, satisfaction quirk, usage condition) earns its place and no redundant filler remains.

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 input schema fully documents the parameter and an output schema exists, the description supplies all necessary invocation context plus enough semantic detail about the content. The tool is a straightforward read, and the description fully covers whether/how it relates to other tools.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already describes the sole parameter completely (Companies House company number, max length, format). The description adds no additional parameter detail, so with 100% schema coverage, a baseline 3 is appropriate; no value is added 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 a specific verb and resource: 'Fetch the complete Companies House charge history for a company.' It clearly differentiates itself from siblings by clarifying it covers specific charges rather than a summary, and explains what data is returned (status, dates, secured parties, flags). The distinction from company_profile.has_charges is explicitly named.

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 an explicit usage condition: 'use this tool when the specific charges matter, not just whether any exist.' This implies an alternative for checking existence (company_profile.has_charges). While it names the summary field rather than the sibling tool directly, the alternative is clear enough for an agent to route correctly.

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?

Even with readOnlyHint, idempotentHint, and destructiveHint=false annotations, the description goes well beyond them: it states the tool never embeds bytes and never returns base64, only reads metadata, and requires a resource-capable MCP client for bytes. It explicitly discloses that tool-only clients cannot obtain the file, which is valuable behavioral context beyond the annotations.

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

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

The description is dense and mostly front-loaded: purpose first, output type second, metadata-only behavior third, and workflow fourth. Almost every sentence earns its place. There's slight redundancy between 'never downloads' and 'can see this result's metadata but cannot obtain the file,' but it's honestly more clarifying than wasteful. A tight 4.

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 no output schema to fall back on, the description fully compensates: it states the exact return shape (resource_link) and its type (company-document:// MCP resource), what metadata fields are available (company, category, page count, size, content types), and the prerequisite steps. This is exactly the completeness needed for a 2-param, no-output-schema resolver 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%—both params are documented in the schema. The description adds semantic nuance beyond the schema by asserting the URL must be passed verbatim and must be an exact document-api URL, and by contextualizing mime_type selection as needing to only be set when multiple representations exist. This is valuable on top of 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 a specific verb-resource pair: 'Resolve a filing's document_metadata link to its authoritative source document.' It clearly distinguishes this from siblings like dd_company_filing_history by explaining that this tool converts the discovered metadata URL into a concrete resource_link rather than listing filings or downloading 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 workflow guidance is provided: 'Use company_filing_history first to find a filing's document_metadata URL,' with follow-on instructions to fetch the actual PDF via resources/read. The description also warns about client capability constraints, telling tool-only clients exactly what they can and cannot do, which is clear when-to-use and when-not-to-use information.

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 (readOnly, openWorld, idempotent, non-destructive), the description discloses key behaviors: it returns raw upstream facts not interpreted DD conclusions, does not fetch document content, reports total_count/returned/has_more truthfully, and never silently truncates. It also explains the not_found error distinct from an empty result.

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 into a first-sentence summary, a core behavior paragraph, and a pagination/filtering/error paragraph. Every sentence provides necessary context, and the most critical information 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?

The tool is a one-page API read with 4 parameters and an output schema. The description adequately covers what is returned, how pagination works, making important distinctions from sibling tools, and how to handle errors, making it comprehensive for an agent to call 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%, so the description doesn't need to restate parameter details. However, it adds value by giving category filter usage examples (category='mortgage', 'insolvency') and clarifying the pagination re-call pattern with start_index=start_index+returned. This complements the schema's already detailed descriptions.

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

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

The description clearly states the tool fetches one page of a company's Companies House filing chronology, with a specific verb ('fetch') and resource. It distinguishes itself from sibling tools (company_officers/psc/charges) by emphasizing it does not auto-fetch every page and does not fetch document 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 guides when to use this tool versus alternatives: it does NOT auto-fetch every page unlike related tools, advises narrowing with category= for specific slices, and notes document retrieval is not performed here. The description also explains how to handle not_found versus zero-filing 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?

It discloses useful behaviors beyond the readOnlyHint/idempotent annotations: resigned officers are excluded by default, include_resigned=true is the opt-in, and pagination is handled internally. These are real operational details that change how an agent calls/de is treated.

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 short sentences, no filler, main purpose explicitly stated up front, and the most important non-obvious behaviors are spaced out clearly. Every sentence contributes value.

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

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

Given the existing output schema and the annotations and the rich schema coverage, the description fully covers what an agent needs to know to correctly select and invoke the tool. It covers the action, the returned data shape, the key parameter option, and the internal pagination behavior.

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 the schema already explains each parameter — including the ignored start_index/items_per_page and the default false for include_resigned. The description mainly re-states what the schema covers, though it adds the note 'historical DD' which gives light additional context.

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?

Starts with 'Fetch officers for a Companies House company number,' which names the exact verb and resource. It then states what is returned (directors, secretaries, other officers) and easily distinguishes this tool from sibling tools like dd_company_charges or dd_officer_appointments.

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 makes clear this is the tool to use for company officer lists and gives a concrete condition for the include_resigned parameter. It does not explicitly mention alternatives such as 'if you need a single officer's appointment history use dd_officer_appointments', so it misses explicit exclusion guidance, but the context is clear.

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

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

The annotations already cover the safety profile (read-only, idempotent, non-destructive), so the description adds value by disclosing exactly which pieces of company data the call returns. It also communicates that the result is a composite profile rather than a single filing or charge record. No contradiction with annotations 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?

The description is compact, front-loads the main purpose in the first sentence, and then adds only useful clarifying details. There is no repeated information from the tool name or title, and 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 single-parameter, read-only lookup with a rich output schema, the description covers the tool's scope, return contents, and prerequisite workflow. Given the strong annotations and schema coverage, the agent has enough information 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 input schema already extensively documents company_number, including format examples and the fact that it comes from company_search, so parameter coverage is effectively 100%. The description reinforces the use of company_search but does not add substantial new parameter meaning beyond the schema.

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

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

The description opens with a specific verb and resource ('Fetch the full Companies House profile for a company number') and then lists the concrete data returned (status, registered address, SIC codes, compliance flags, outstanding charges). This clearly distinguishes it from siblings like dd_company_charges, dd_company_filing_history, and dd_company_officers.

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

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

The description gives a clear prerequisite: 'Use company_search first to find the company number.' This establishes the expected workflow. It does not explicitly mention when to prefer sibling tools such as dd_company_filing_history over this one, but the listed return fields and prerequisite provide adequate selection context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond that: it flags overseas corporate PSC entries as a beneficial-ownership risk signal and explains the special explanatory note for widely-held PLCs with no registrable PSC.

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

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

The description is short, direct, and front-loaded with the core action and resource. Every sentence contributes useful information about what is returned, a risk flag, or a meaningful edge 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 read-only tool with an output schema and helpful annotations, the description covers the main content, a special risk behavior, and an unusual empty-result case. Nothing important 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?

There is only one parameter, company_number, and the input schema already describes it fully with length constraints, format, and an example. The description adds no parameter-level detail, which is acceptable given 100% schema coverage, so the baseline score applies.

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

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

The description opens with a specific verb and resource: 'Fetch Persons with Significant Control (beneficial ownership) for a company.' It also names the key data returned, distinguishing it from related company tools like dd_company_officers and dd_company_profile.

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

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

The resource and terminology make the use case clear, but there is no explicit guidance about when to prefer this tool versus alternatives such as dd_company_officers or dd_company_profile. The distinction is implied strongly by 'beneficial ownership' rather than stated directly.

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?

It discloses behavioral details beyond the read-only/idempotent annotations: internal DD severity sorting, the fact that the notice label is a source fact, the legal effectiveness of Gazette notices, and the notice_numeric_id trail. These are substantive additions that go beyond simply saying it is read-only.

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 core purpose is front-loaded in the first sentence, with follow-up and legal context in compact paragraphs. A small amount of redundancy exists between the opening phrase and the second sentence, but the organization is clean.

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, combined with the rich annotations and output schema, gives an agent enough to correctly invoke the tool and understand the result: legal significance, sorting behavior, result identifier, and how to get the full notice. Nothing critical is missing.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with all parameters described, so the schema does the heavy lifting. The description adds only minor context such as 'authoritative Gazette notice-code taxonomy' and does not meaningfully explain aliases or extended date semantics beyond the schema.

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

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

The description names the exact operation and resource: searching The Gazette's corporate-insolvency notice index by entity. It clearly distinguishes this from generic gazette or company searches by referencing the Gazette notice-code taxonomy and the notice:// result 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 explains when the tool is appropriate—searching the official Gazette insolvency record—and provides a concrete follow-up: use notice://{notice_numeric_id} for full legal wording. It stops short of explicitly naming when to use or not use sibling alternatives like dd_gazette_notice.

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?

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?

Annotations already carry safety profile, and description adds behavioral detail: it returns both current and historical appointments, includes entries for dissolved or insolvent companies not found elsewhere, and always returns full history. It does not add rate-limit or auth context, but description 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 front-loaded with the core purpose, and all information is directly relevant. The second sentence is somewhat long, but its chain details are essential for correct historical discovery; the final version re-emphasizes the full-history 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?

With a single required parameter, an output schema, and strong annotations, the description is fully sufficient. It includes the preceding workflow step, what the tool returns, its unique historical value, and a flag behavioral constraint about no current-only filter.

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 and the schema coverage is 100%, so the schema already documents officer_id thoroughly. The description adds workflow context by saying the ID comes from company_officers, which helps an agent know how to find and supply it correctly.

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: "Fetch a person's full company appointment history by officer ID." It clearly differentiates this tool from siblings by emphasizing historic and dissolved/insolvent appointments, setting it apart from current-officer and profile 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 instructs the agent to use company_officers first to obtain an officer_id, then use this tool for historical discovery. It also states the limitation clearly: "Always returns full history; there is no current-only filter, since historical discovery is the point."

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?

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 cover readOnlyHint, idempotentHint, and destructiveHint. The description adds value by describing the return content (paginated page of bill summaries with specific fields), the authoritative source claim, and the downstream step. 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?

Three sentences, front-loaded with the usage directive, and every sentence carries essential information: what it does, what it returns, and how to proceed for more detail. No 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 output schema exists and the schema documents pagination via offset and has_more, the description is largely complete. It covers the return fields and the follow-up tool. It doesn't explicitly mention pagination mechanics, but that is covered in the schema, so the description remains adequate.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all parameters are already fully documented. The description mentions keyword, session, house, and stage, but these map directly to schema parameters without adding new meaning or usage details 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?

States a specific verb (search) and resource (UK parliamentary bills) with clear dimensions (keyword, session, house, legislative stage). It clearly distinguishes from sibling law_bills_get_bill by noting it returns summaries and pointing to that tool for full detail.

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

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

Explicitly says 'USE THIS TOOL WHEN searching...' and provides a follow-up action: pass a bill_id into bills_get_bill for full detail. This gives clear context and an alternative, leaving no ambiguity about when to use this tool versus the sibling.

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

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

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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses concrete behaviors: the one-page limit, the ordering of oral before written evidence, title/witness caps, rendering rules for organisation witnesses, null semantics, and the total field. This gives the agent a detailed operational picture far beyond the annotation hints.

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 core usage condition, then proceeds logically through output characteristics, formatting rules, and pagination. Every sentence carries distinct information without redundancy, and the 'Authoritative source' note adds provenance without padding. Length is appropriate for the tool's complexity.

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 are covered. The description covers pagination, ordering, formatting edge cases, parameter interactions, and the source authority. An agent has everything needed to invoke this tool correctly and interpret the results.

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 meaning by explaining the combined ordering for evidence_type='both', the purpose of max_title_chars (avoiding context blow-up), and how offset interacts with the combined sequence for pagination. This is meaningful added context, though the schema already covers individual parameter meanings.

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 committee_id and want the oral and written evidence submitted to it', which names a specific verb ('search evidence'), a resource ('committee evidence'), and the key precondition (committee_id). This clearly differentiates it from sibling tools like law_committees_search_committees and law_committees_get_committee, which target committee discovery or metadata rather than evidence.

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

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

The 'USE THIS TOOL WHEN' clause explicitly states the condition for use. It also gives pagination guidance ('re-call with offset=offset+returned while has_more is true'), which directs the agent on iterative usage. It does not mention when not to use it or name alternative tools, but the context is clear enough for selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, 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?

Annotations already mark this as read-only, idempotent, and non-destructive, so the description only needs to add non-safety behavior. It does this well: exact matching rules, normalization rules, the fact that extra words are never discarded, null-on-no-match behavior with no defaults, and the content of notes on failure.

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 usage trigger and is organized into clear sections: when to use, matching rules, successful return values, and unresolved-result behavior. Every sentence earns its place; nothing is redundant or decorative.

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 complete for a one-parameter lookup tool. It covers success behavior, failure behavior, parameter constraints, and the fallback sibling tool. The output schema handles structured return details, and the description adds the semantic meaning an agent needs to interpret the response correctly.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema already gives examples, but the description adds crucial semantics beyond it: the value must exactly equal a category name, not a free-text description or commodity code. It clarifies the potentially misleading 'commodity_code' property name and explains normalization and non-fuzzy matching in detail.

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 job: given a known UK VAT category name, return its VAT treatment. It explicitly distinguishes this from a free-text VAT classifier or tax advice, and names the sibling law_hmrc_search_guidance as the fallback, so an agent can tell them apart.

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 opening line is an explicit when-to-use trigger: use when you know the exact VAT category name. It also explains when not to use it (free-text queries, extra qualifying words) and tells the agent what to do after an unresolved result: retry with a listed name or call hmrc_search_guidance.

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

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

Annotations already declare readOnlyHint, 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?

Annotations cover readOnly/idempotent/openWorld, and the description goes well beyond them: it explains truncation behavior (content capped per max_chars, check content_truncated), error behavior (not_found rather than a plausible-but-wrong node), what is and is not returned (own heading, never neighbouring Part/Chapter), and a domain caution about extent. This is rich behavioral disclosure that annotations alone do not 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?

Front-loaded with the use-when clause and structured into short paragraphs, each carrying a distinct payload (scope, return boundaries, truncation, cross-type behavior, error, extent caveat, alternative). Slightly long but every sentence earns its place; 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?

An output schema exists, so return values need not be explained, and the description still adds the essential context: truncation signals, not_found behavior, extent caveat, and the raw-XML alternative. For a 5-param, 4-required tool with cross-type input semantics, nothing an agent needs to call it correctly is missing.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so the baseline is 3. The description adds meaningful meaning beyond the schema for two params: it clarifies that 'section' takes the bare number regardless of Act/SI article noun, and it justifies the max_chars default and when to raise it. It does not re-explain type/year/number, but the added rationale for the ambiguous params earns above 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?

States a specific verb (get) and resource (parsed text of a specific section/regulation/article), and distinguishes from siblings by naming the read_resource alternative and pointing to legislation_get_toc for valid numbers. An agent can tell it apart from law_legislation_get_toc and law_legislation_search without opening schemas.

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?

Opens with 'USE THIS TOOL WHEN you have a known Act / SI', names the alternative (read_resource for raw CLML XML), and gives the fallback (legislation_get_toc for valid numbers). Explicit when and when-not guidance is present.

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 cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the bar is lower, yet the description adds real behavior: large statutes are paginated, check has_more/total_items, and items with no heading are returned as bare ids. It stops short of describing ordering guarantees or error behavior on bad type/number, so a 4 rather than a 5.

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

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

Front-loads the trigger and output shape before pagination and the alternative, and every sentence carries information (id formats, heading pairing, pagination, alternative). It is longer than strictly necessary — the paragraph format could be tightened — but there is 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?

For a 5-parameter paginated lookup with an output schema already present, the description covers the remaining gaps: what the structure looks like, the id format to feed downstream, pagination controls, the rare titleless-entry edge case, and the competing read_resource route. Nothing an agent needs to call it correctly is missing.