UK Legal Research

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

The annotations already declare readOnly, idempotent, and non-destructive. The description adds concrete behavioral detail about summary truncation and the summary_truncated response flag, which helps the agent anticipate output limits.

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, roughly four sentences, with a clear 'USE THIS TOOL WHEN' lead and no redundant filler. Each segment (condition, returns, follow-up) 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?

With a comprehensive output schema, read-only annotations, and full parameter documentation, the description covers the essential context: when to call, what it returns, truncation behavior, and suggested subsequent actions. It's 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?

The schema already documents both parameters comprehensively (source of bill_id, default and bounds for max_summary_chars), so the description's mention of truncation adds a minor cross-reference to the response flag but doesn't materially expand on the schema.

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

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

The description clearly states the tool retrieves full bill detail including sponsors, current stage, long title, summary, and Royal Assent date, and specifies the trigger condition (having a bill_id from bills_search_bills). This distinguishes it from the sibling search tool by framing it as the detail-fetching follow-up.

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 conditional: 'USE THIS TOOL WHEN you have a bill_id (from bills_search_bills) and want the full detail.' It also provides a clear follow-up action (parliament_search_hansard) and alternative search suggestion, though it doesn't explicitly name competing tools to exclude.

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 value beyond the readOnlyHint annotation by detailing the return structure (paginated page of bill summaries with title, houses, stage, Act status) and mentioning pagination implicitly. It also notes the workflow to bills_get_bill. However, it does not disclose potential rate limits or error conditions, though these are minor for a read-only search. The description is consistent with annotations.

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

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

The description is concise and well-structured: it leads with the usage trigger, then the return summary, then the follow-up workflow, and ends with a credibility statement. Every sentence serves a purpose with no fluff, and the most important usage guidance 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 description covers the essential usage context: when to use, what it returns, and how to follow up. It mentions pagination and the fields returned, which aligns with the output schema. The guidance to use bills_get_bill for detail completes the workflow. For a search tool with a rich schema and output schema, this is comprehensive.

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

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

Schema coverage is 100%, so all parameters are already well-documented in the input schema. The description mentions search dimensions (keyword, session, house, stage) which map to parameters, but it does not add further semantic depth beyond what the schema provides. It appropriately relies on the schema's detailed parameter 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 explicitly states the tool's function: searching UK parliamentary bills by keyword, session, house, or legislative stage. It clearly distinguishes itself from the sibling bills_get_bill, which provides full detail, by noting it returns summaries. The purpose is unambiguous and differentiated.

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

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

The description begins with 'USE THIS TOOL WHEN searching...' which is an explicit usage instruction. It also directs the agent to bills_get_bill after calling for full detail, clearly defining when to use this tool versus its sibling. The statement 'Authoritative source for UK parliamentary bill status' further reinforces its intended role.

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, covering safety. The description adds valuable behavioral context: it returns only small snippets (not full paragraphs), and it discloses the regex fallback to literal substring search if compilation fails. This goes beyond the annotations and is helpful for setting expectations.

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

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

The description is well-structured and front-loaded with a directive usage trigger, followed by concise notes on return format, post-processing, and fallback behavior. It contains no redundant filler, though the 'AFTER calling' clause could be seen as slightly verbose but is still informative.

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 moderate complexity (4 parameters, output schema present), the description covers purpose, usage, output format, and follow-up actions, which is sufficient for tool selection. It does not mention max_hits or case_insensitive defaults, but those are already well-documented in the schema, so the description need not repeat them.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add new parameter-level meaning beyond the schema; it only restates the regex fallback already present in the pattern property description. The schema itself documents all four parameters well, so no extra benefit is derived from the description.

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

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

The description clearly states that the tool searches paragraphs within a specific UK court judgment matching a pattern, using a specific verb and resource. It also distinguishes from siblings by explicitly mentioning judgment_get_index for paragraph-number navigation and judgment_get_paragraph for reading full paragraphs.

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

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

The description opens with 'USE THIS TOOL WHEN you have a judgment slug and want to find paragraphs whose text matches a pattern', providing a clear trigger condition. It also gives a concrete use case, an explicit alternative for index navigation, and follow-up guidance to retrieve full paragraphs, making usage guidance explicit and actionable.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds real value on top: coverage window (roughly early 2000s onward), fallback for older authorities, the returned summary fields, and a warning about unstable web URLs. The one defect is the advice to 'narrow with court + year filters', which conflicts with the schema's own note that from_date/to_date are silently ignored upstream — an agent following that tip would waste a call.

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 trigger phrase, then short paragraphs for returns, after-call routing, and coverage — each sentence carries information. It is on the long side for a single tool, and one of its lines (year filters) does not earn its place because it is inaccurate.

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 it does not need to explain return values, yet it does briefly and harmlessly. What it omits is consistency: it recommends year filtering while the schema says date filters are no-ops, leaving the agent with two conflicting stories about how to narrow 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 description coverage is 100%, so per-parameter semantics (court slugs, judge surname matching, limit slicing, date caveats) are already carried by the schema. The description adds only marginal parameter context by enumerating the searchable facets and the party-name narrowing tactic; baseline 3 is right 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?

Opens with an explicit verb and resource ('searching UK case law') plus the exact facets it accepts (party names, court, judge, date, free text). It also distinguishes itself from the near-siblings by naming judgment_get_header / judgment_get_index / judgment_get_paragraph, case_law_grep_judgment and citations_resolve as downstream steps rather than substitutes.

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

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

Gives an explicit when-to-use trigger, then a full after-call routing map: slug into judgment_get_*, neutral citation into citations_resolve, grep for in-judgment text. It even states the exclusion ('do not supplement' with web search) and the narrowing strategy for ambiguous party names, so no alternative is left to inference.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses refusal behavior: 'Refuses (status: upstream_validation) if confidence is 0.0... or if a neutral citation has no resolved_url.' It also states 'no network call' and warns against manufacturing citations. This adds significant behavioral context 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?

The description is front-loaded with the critical workflow instruction and is organized into short, purposeful sentences. There is some repetition ('do NOT construct the input fields yourself' and 'do not guess'), but it is a safety-critical guardrail that benefits from emphasis. Overall, every sentence earns its place, though minor tightening could remove redundancy.

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

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

Given the tool's complexity (14 parameters, multiple citation types) and the existence of an output schema, the description fully covers what an agent needs: the pipeline sequence, refusal conditions, the anti-fabrication rule, and the authoritative format. It does not explain return values, but the output schema covers that. The description is complete for its role.

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

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

Schema description coverage is 100%, so the schema fully explains each parameter. The description adds an overarching rule that all parameters must come from citations_resolve, but this is more of a usage guideline than parameter semantics. The schema already covers details like confidence refusal and the EU-retained-law raw handling, so the description adds no new per-parameter meaning. 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 and resource: 'produce the correctly formatted OSCOLA citation string.' It also distinguishes from siblings by explicitly saying 'USE THIS TOOL AFTER citations_resolve,' placing it clearly in the pipeline relative to citations_parse and 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 provides explicit when-to-use guidance: 'USE THIS TOOL AFTER citations_resolve' and 'Pass the parsed fields returned by citations_resolve directly into this tool.' It also gives strong exclusions and failure-handling instructions: 'DO NOT construct the input fields yourself,' 'surface the failure and ask the user for the source URL or better identifying details.' This is comprehensive and actionable.

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

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

Annotations already mark the tool as readOnly/idempotent/non-destructive. The description adds valuable behavior details: fetching judgment XML from TNA, parsing OSCOLA citations, grouping by type, deduplicating, and sorting. It also discloses that the tool does not resolve citations, which is a key behavioral limitation.

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 condition and is organized into three focused paragraphs. All sentences contribute useful context, though the format is slightly more verbose than necessary for the information conveyed.

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 precondition (judgment slug), what the tool does (parse TNA XML for OSCOLA citations), output characteristics (grouped, deduplicated, sorted), and follow-up action (use citations_resolve). With an output schema present, it is fully complete for this 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?

The schema description for case_uri is thorough (slug format, use 'uri' field, no prefix), providing 100% coverage. The description only reiterates the concept of a 'judgment slug' without adding new parameter-level semantics, 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 maps all citations a judgment makes, including cases, legislation, SIs, and retained EU law. It distinguishes itself from sibling tools by emphasizing the network-wide mapping and integration with citations_resolve.

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

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

It explicitly starts with 'USE THIS TOOL WHEN you have a judgment slug and want to map every citation it makes' and directs the user to pass citations through citations_resolve after. This provides clear when-to-use and a follow-up alternative, aligning with the sibling tool's purpose.

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

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

Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description adds critical behavioral context: parsing is pure regex by default, optional disambiguation invokes the client's own LLM via MCP sampling, and recognition of citation shape does not guarantee document existence. This meaningfully informs the agent of limitations and side effects (model-in-the-loop) that annotations cannot 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 well-structured with clear sections: a bolded usage trigger, a list of supported citation types, parsing behavior, and a follow-up instruction. It is front-loaded with the most important 'when to use' information and every sentence contributes operational value without redundancies.

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 only 2 parameters, an output schema, and rich sibling context, the description fully covers the essential operational details: input type, output scope, disambiguation behavior, URL resolution, and the requirement to verify via citations_resolve. It clearly differentiates itself from the resolve and format siblings, so an agent can 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 coverage is 100%, and the parameter descriptions already fully explain the text and disambiguate parameters. The tool description repeats the supported citation types and the disambiguation behavior, adding little new semantic value beyond the schema. It does hint at URL resolution as output, but that is not a parameter-level 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 opens with a specific action ('extract and classify every OSCOLA-style citation') and identifies the target resource (free text). It lists concrete citation types and explicitly separates itself from sibling tools like citations_resolve by stating what it does not do (confirm existence). The verb and scope are precise and 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 clearly states when to use the tool ('USE THIS TOOL WHEN you have free text... and want every OSCOLA-style citation... extracted and classified') and explicitly directs the agent to follow up with citations_resolve for verification. It does not explicitly say when not to use it, but the alternative/next-step guidance is strong and actionable.

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

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

Beyond the annotations, the description reveals live TNA HEAD-check behavior, confidence scores dropping to 0.0 on non-200 responses, and ToolError with retryable semantics. It also warns about quoting low-confidence results, which is important behavioral context for downstream use.

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 front-loads the usage directive, but some safety warnings are repeated (e.g., not formatting or quoting unresolved citations). The redundancy is understandable for risk mitigation but prevents a perfect conciseness score.

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 input, output shape, error behavior, retry semantics, and downstream safety considerations. Given the presence of an output schema, the additional context about confidence and resolved_url is sufficient for an agent to use the tool correctly.

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

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

The schema fully describes the single required citation parameter with length constraints and concrete examples. The tool description additionally enumerates accepted citation types, making the parameter semantics clear and actionable.

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

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

The description clearly states that the tool parses and resolves a single OSCOLA citation, returning parsed fields and a resolved_url. It also distinguishes this from sibling tools like citations_parse and citations_format_oscola by emphasizing real-document resolution.

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 agents to use this tool before constructing an OSCOLA citation string or confirming that a citation points to a real document. It also provides critical guidance about not manufacturing citations when resolution fails, which clearly defines when and how to use the 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, idempotentHint, and non-destructive behavior, lowering the burden. The description adds valuable behavioral context by noting that committee detail and member list are fetched in parallel, and it reveals the intended follow-up workflow. This goes beyond simple safety disclosure, though it doesn't detail response structure or pagination (which are covered by the output schema).

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

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

The description is compact and front-loaded with the key usage condition, followed by the action and a next-step suggestion. Every sentence provides distinct value with no redundancy.

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

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

For a single-parameter get-by-ID tool with rich annotations and an output schema, the description fully covers the necessary context: when to use it, what it returns, and what to do next. The workflow hint to committees_search_evidence completes the contextual picture.

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 single parameter committee_id is already well-described in the schema as coming from committees_search_committees results. The description does not add additional semantic meaning beyond that, 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 this tool fetches committee detail and member list, with an explicit 'USE THIS TOOL WHEN...' condition. It distinguishes itself from sibling search tools by requiring a committee_id and focusing on metadata + membership.

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 ('when you have a committee_id and want metadata + current membership') and adds a workflow pointer to committees_search_evidence. However, it does not explicitly state when not to use it or name alternative tools for lookup scenarios, 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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the workflow position and the exact handoff field name into the evidence tool. It stops short of stating anything about result-set size or paging behavior, which is the only remaining gap.

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 lines, front-loaded with the trigger condition in caps, then return payload, then the next-step handoff. Every sentence carries a distinct, actionable fact with no repetition of the schema.

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?

Workflow entry and exit are both described, the return contents are summarized, and an output schema exists so field-level return detail is handled elsewhere. For a three-parameter read-only search, an agent has everything needed to call it and chain onward 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 explains limit bounds, the query title-search caveat, and the committee_id provenance, so the baseline is 3. The description adds the downstream use of the returned ID but contributes no additional parameter semantics of its own.

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?

Names a specific verb and resource ('identifying a committee inquiry or business') and states what it returns (IDs, titles, types, dates, report/status metadata). It is clearly separable from the sibling committees_search_evidence, which is a downstream step rather than the same lookup.

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

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

Gives an explicit trigger ('USE THIS TOOL WHEN identifying a committee inquiry or business before evidence retrieval') and an explicit follow-up ('AFTER calling, use an exact ID as committee_business_id in committees_search_evidence'). The when-to-use and the alternative are both spelled out, so nothing is left to inference.

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 readOnly/idempotent/non-destructive safety, so the description's added value is the return shape and the downstream chaining contract (pass committee_id onward), which is genuinely useful workflow context. It does not mention result-volume or upstream-search ordering, though the schema covers the latter.

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 short blocks, front-loaded with the trigger condition, then the return contract and follow-on routing. No sentence is redundant with another, and nothing buries the invocation condition.

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, full annotation coverage, and 100%-documented parameters, the description only needs to supply purpose, trigger, and chaining — all of which it does. Nothing required to call this tool 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 description coverage is 100% and the schema itself explains each parameter's intent (including why limit defaults to 100), so the description adds no parameter-level meaning beyond its one-line mention of 'name, house, or active status'. Baseline 3 applies 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?

States a specific verb (search/list) and resource (UK parliamentary select committees) plus the three filter axes: name, house, active status. It also declares the return payload (name, house, active status, ID), so an agent can distinguish it from committees_get_committee and committees_search_evidence without opening any schema.

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 an explicit 'USE THIS TOOL WHEN' trigger condition and routes the agent forward to committees_get_committee for membership and committees_search_evidence for evidence. It stops short of naming an explicit exclusion ('do not use for X'), but the search-versus-retrieve split against its closest siblings is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, but the description adds substantial behavioral detail beyond them: one-page default of 20, source ordering of oral-then-written evidence, title and witness caps, null-witness semantics, and the upstream-before-pagination filter behavior. This is exactly the context an agent needs to interpret pagination and output correctly.

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 use case and then proceeds through pagination, ordering, formatting, and workflow in a logical sequence. It is dense but every sentence carries operational value; the only slight cost is that several distinct concerns are packed into one block without paragraph breaks.

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

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

Given an 8-parameter tool with an output schema and rich annotations, the description covers the remaining gaps: pagination mechanics (offset=offset+returned while has_more is true), source ordering, witness rendering, and how to obtain committee_business_id. Nothing needed to call it correctly appears to be 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%, so the baseline is 3, but the description adds genuine meaning beyond the schema: evidence_type='both' ordering (all oral first, then written, each newest first), max_title_chars context-blow-up rationale, and witness-list capping. It does not re-explain every parameter (e.g., date range semantics are left largely to the schema), but it compensates well for the most consequential parameters.

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 and resource ('retrieving committee evidence') and scopes it to identified inquiries. It is clearly distinguishable from sibling tools like committees_search_businesses and committees_search_committees, which it references as upstream sources.

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

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

Explicitly says when to use it ('USE THIS TOOL WHEN retrieving committee evidence, especially for an identified inquiry') and names the alternative workflow: first call committees_search_businesses and pass its exact committee_business_id. It also tells the agent where committee_id comes from.

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 indicate readOnlyHint, idempotentHint, and non-destructive behavior, which match the description's 'get' action. The description does not mention side effects, but the annotations cover this. 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 concise, using two short sentences to convey the purpose and parameter 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?

The description provides enough context for retrieval, including the return format (rendered JSON with messages array). The output schema exists and covers the response, so no further detail is required.

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?

Both parameters are fully described: 'name' as the prompt identifier and 'arguments' as an optional mapping. The schema already covers this, and the description reinforces the meaning with no ambiguity.

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

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

The description clearly states that the tool retrieves a prompt by name with optional arguments, distinguishing it from sibling tools like list_prompts which list available prompts. The verb 'get' and resource 'prompt' 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 implies usage when a specific prompt is needed, and the sibling list_prompts provides the alternative for listing. Though not explicit, the context is sufficient for an agent to decide when to use this tool.

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

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

Annotations already mark the tool as readOnly and idempotent, and the description adds valuable behavioral context: default sandbox connection, production override via HMRC_API_BASE, required OAuth credentials, and that it raises if credentials are missing. This goes beyond the structured fields 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 front-loaded with the core purpose, followed by return details and environment notes. Every sentence provides value, though the environment configuration section could be trimmed without losing clarity.

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, the description covers the main use case, return fields, environment defaults, and error behavior. The presence of an output schema further reduces the need to explain return format, making this 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?

The schema fully describes the only parameter (vrn) with format and example, and the description does not add new parameter information. With schema coverage at 100%, 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 states a specific action and resource: 'USE THIS TOOL WHEN you have a 9-digit VAT Registration Number and need that business's Making Tax Digital VAT mandate status.' It clearly explains the return value (mandated status, effective date, trading name) and distinguishes from other HMRC tools like hmrc_get_vat_rate.

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

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

The description provides 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.' It also gives environment setup and warns against inferring status without credentials, though it does not name alternative tools for when-not-to-use.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds value beyond them: bounded source-order output, reported truncation, returned provenance/metadata, and an explicit failure-handling rule against inferring content. Return-format detail is partially redundant with the existing output schema.

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

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

The trigger condition is front-loaded in the first sentence and the total length is short. The source-attribution line is slightly redundant with the title, but it earns its place as an allowlist/trust signal for an open-world fetch.

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 full output schema and complete annotations, the description supplies the remaining essentials: read-only fetch semantics, truncation behavior, provenance return, and the do-not-infer-on-failure rule. The only gap is not telling the agent where to obtain a reference or family slug when it has none.

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 four parameters (including the manual_url OR family+reference alternative and the 500–20000 max_chars bound) are already documented in the schema. The description mentions 'bounded' text and truncation reporting but adds no syntax or selection guidance beyond the schema, 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 states a specific verb (read) and a specific resource (a cited HMRC internal-manual page), and the 'cited ... must be read' framing implicitly separates it from the search tools in the sibling list. It does not, however, name a sibling such as hmrc_search_guidance or legislation_get_section to make the boundary 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?

'USE THIS TOOL WHEN a cited HMRC internal-manual page must be read' gives a clear triggering condition, and 'if retrieval fails, do not infer the page's contents' supplies a useful negative rule. Missing is the prerequisite path: when the agent only has a topic, it should search for a reference first, and no alternative is named.

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 mark the tool read-only, idempotent, and non-destructive; the description adds important behavioral details such as exact-match normalization, the rule that extra qualifying words are not discarded, the null response for unresolved queries, and the fact that notes list category names. This goes well beyond the structured 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 triggering condition and is generally dense and efficient. A few details about return fields overlap with what an output schema would likely provide, but every section contributes actionable guidance.

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

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

For a single-parameter, read-only, idempotent lookup tool, the description covers when to use it, exact matching semantics, success and failure output shapes, and a retry/alternative path. Nothing essential 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 coverage is 100%, but the description materially enhances the single parameter by clarifying it must exactly equal a category name, not free text, and by giving normalization rules and explicit examples. It also explains what happens when the parameter does not resolve to a category.

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 the exact purpose: a named-category VAT lookup, and explicitly contrasts it with a free-text classifier. It is specific about the resource and behavior, and the sibling tools like hmrc_search_guidance are clearly distinct.

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 begins with 'USE THIS TOOL WHEN you know the UK VAT category name', gives explicit negative guidance ('not a free-text VAT classifier or tax advice'), and names hmrc_search_guidance as the follow-up alternative after an unresolved result. This is model-level routing guidance, not just a vague hint.

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 read-only, idempotent, open-world, non-destructive behavior. The description adds real value beyond that: it names the underlying source API and warns that result descriptions 'do not establish the contents of a cited page', which prevents the agent from treating snippets as authoritative. It stops short of noting rate limits or result-ranking 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?

Front-loaded trigger sentence followed by return shape, caveat, and next-step routing — no filler. The enumeration of returned fields partially duplicates the output schema, which is the only small inefficiency.

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, yet the description still supplies the interpretive caveat about snippet reliability and the cross-tool handoff that no structured field carries. An agent has everything needed to call it 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 description coverage is 100% — both 'query' and 'limit' are fully documented in the input schema, including bounds and examples. The description adds no parameter-level detail (e.g. query syntax or search-operator support), so the baseline 3 applies.

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

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

States a specific verb + resource + source ('discovering HMRC GOV.UK guidance on a topic', 'GOV.UK's HMRC-filtered content search API'), which is distinct from legislation_search or parliament_search_hansard siblings. The mention of hmrc_get_manual_page as a follow-up further delimits its role in the HMRC tool cluster.

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 an explicit trigger ('USE THIS TOOL WHEN discovering HMRC GOV.UK guidance on a topic') and gives a conditional next step ('use hmrc_get_manual_page when a result is an HMRC internal-manual URL'). It lacks an explicit negative case (e.g. 'do not use for legislation text'), but the usage context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. Description adds useful context about being the authoritative source for UK judgment metadata, and the workflow context. No contradiction or hidden behavior disclosed, but adds value beyond annotations.

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

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

Three sentences, front-loaded with 'USE THIS TOOL WHEN', each sentence earns its place: usage trigger, workflow, authority. No redundancy or 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?

Given a single parameter, full schema coverage, output schema present, and strong annotations, the description covers the workflow, tool distinction, and metadata scope. Complete for a simple read-only tool.

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

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

Schema coverage is 100% with a clear description and examples for the 'slug' parameter. The description adds the context of needing a slug from case_law_search but doesn't provide new parameter-level semantics 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?

Specific verb+resource: 'get metadata' for a judgment header, with explicit list of metadata types (parties, judges, neutral citation, court, dates). Clearly distinguishes from siblings judgment_get_index and judgment_get_paragraph by focusing on header metadata vs paragraphs.

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

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

Explicitly states when to use: 'when you have a judgment slug and need metadata'. Provides workflow: call case_law_search first, then use judgment_get_index/paragraph. Naming alternatives and prerequisite tools makes 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, idempotentHint, and destructiveHint false, so safety is covered. The description adds that the tool returns an eId and preview line for every paragraph, which is useful behavioral context beyond the annotations. It does not mention error handling or pagination, but the output schema likely covers return structure.

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 usage trigger. Every sentence provides necessary information: what it does, when to use it, and how it fits with other tools. No wasted words 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 one-parameter tool with rich annotations and an output schema, the description fully covers purpose, usage, and relationships to related tools. It even includes the output format (eId + preview line), making it complete for an agent to select and 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?

The input schema fully describes the single 'slug' parameter with an example. The description adds value by explaining how to obtain the slug ('Call case_law_search FIRST to get the slug'), which is not in the schema. Since schema coverage is 100%, the baseline is 3, and the workflow hint lifts it to 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 states 'get the paragraph navigation index (eId + preview line for every paragraph)' with a specific verb and resource. It clearly distinguishes from siblings by mentioning judgment_get_paragraph for full text and case_law_grep_judgment for content 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?

It explicitly says 'USE THIS TOOL WHEN you have a judgment slug and want the paragraph navigation index', and provides a clear workflow: call case_law_search first to get the slug, then pass an eId to judgment_get_paragraph or use case_law_grep_judgment. This gives both when-to-use and alternatives.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description adds value by stating it returns paragraph XML content and a typical token range. It could mention error handling or what happens if eId is invalid, but the key behavior is covered.

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

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

Three concise sentences with no fluff. The purpose is front-loaded, and each sentence adds crucial navigational or return-value information. Perfectly sized.

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 full annotations, the description still manages to provide essential workflow (call judgment_get_index first) and alternative search method. 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 coverage is 100% and includes a detailed eId description with normalization rule. The description itself doesn't add new parameter details beyond referencing them, so baseline 3 is appropriate.

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

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

The description clearly states the tool gets a judgment paragraph's full text given a slug and eId. It distinguishes from siblings by explicitly routing users to judgment_get_index for eIds and case_law_grep_judgment for content-based 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?

Provides explicit when-to-use criteria ('when you have a judgment slug + LegalDocML eId and want that paragraph's full text') and names alternatives (judgment_get_index, case_law_grep_judgment). This is exemplary 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?

Goes well past the annotations (which only declare read-only/idempotent/open-world). It discloses that only the provision's own text is returned (never a neighbouring Part/Chapter), that a missing provision raises not_found instead of returning a plausible neighbour, the CLML source with an explicitly marked public-HTML fallback, and post-call checks on extent and content_truncated.

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 trigger condition is front-loaded in the first clause, followed by behavioural guarantees, then post-call guidance, then alternatives. Every sentence carries distinct information with no restatement of the name or title.

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 read tool with an output schema and full annotation coverage, this covers the remaining gaps: numbering conventions, missing-provision behaviour, source provenance, and a truncation workflow. Nothing an agent needs to call it correctly or interpret the response is absent.

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

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

Schema description coverage is 100%, so the schema already explains 'type', 'year', 'number', and the bare-number rule for 'section'. The description reinforces the bare-number convention and points to content_truncated, but adds little parameter meaning the schema does not already carry.

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 and resource ('want the parsed text of a specific section, regulation, or article') and scopes it to a known Act/SI. It explicitly contrasts with legislation_get_toc and read_resource, so an agent can pick it out of a crowded sibling list without opening a schema.

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 an explicit trigger ('USE THIS TOOL WHEN you have a known Act / SI'), and gives alternatives with their selection conditions: legislation_get_toc to discover valid numbers, read_resource for raw CLML XML. Preconditions and fallbacks are all named.

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, the description discloses that results are XML ids and titles in document order, includes structural elements and provisions, retains rare untitled provisions as bare ids, and is paginated with offset/limit. It also tells the agent to inspect has_more and total_items for large statutes, which is useful behavioral guidance for consuming the 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 front-loaded with the primary usage condition, then follows with return details, downstream guidance, and an alternative resource. Every sentence supports correct selection or invocation, and the source note adds useful provenance without bloat.

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, paginated TOC tool with full schema coverage, annotations, and an output schema, the description provides enough context to select it, understand the shape of results, handle pagination, and route to legislation_get_section or read_resource afterward.

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

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

Schema description coverage is 100%, so the schema already documents type, year, number, limit, and offset, including examples and pagination behavior. The description reinforces pagination and downstream use of bare provision numbers, but adds little parameter-specific meaning beyond what the schema provides.

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 and resource: getting the structural table of contents for a known Act/SI, including parts, chapters, sections, regulations, and articles. It clearly distinguishes this from legislation_get_section by explaining that the TOC is used first and its bare provision number is then passed to the section 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?

It gives an explicit trigger: use this when you already have a known Act/SI and want the structural listing. It also routes follow-up work to legislation_get_section and points to read_resource for the full raw listing, covering both primary usage and alternatives.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: the automatic full-text fallback on WAF/non-XML failures, the search_mode="fulltext_fallback" marker, the warning that fallback relevance is not title-ranked, and the explicit statement that render-pending/ordinary HTTP errors do not trigger it. That is precisely the kind of hidden behavior an agent would otherwise misread.

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 trigger condition and the chaining instruction, which is the right order. It runs long and the 'Filter discipline' passage restates what the type/year schema descriptions already say, so a few sentences could be trimmed, but nothing is 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?

Even though an output schema exists, the description names the returned fields and next_steps hints so the agent knows what it can chain on, and it fully documents the fallback mode. Nothing needed to call or interpret the result 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%, so the schema carries the parameter definitions; the description mostly reinforces them (exact-match type/year, fulltext semantics). It does add a workflow-level insight the schema lacks – that guessing a year can zero the result set and you should read the year off results instead – but much of the filter discussion duplicates schema text.

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 and resource ('searching UK Acts and Statutory Instruments') plus the search modes (title, phrase, full-text), which clearly separates it from structural siblings like legislation_get_toc and legislation_get_section. An agent can tell exactly what to reach it for.

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 an explicit 'USE THIS TOOL WHEN' condition and adds an 'AFTER calling, chain to legislation_get_toc then legislation_get_section' routing rule. It also gives negative guidance for the filters (only use type/year when you already know the value; omit year and read it from results), which is real when-not guidance.

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

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

The annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds that the result is JSON metadata, which is useful context. No contradictions are present.

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 brief, direct, and free of unnecessary detail. Two sentences convey the action and the return format efficiently.

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 no-argument list operation, the description is sufficiently complete. It names the return type and the key fields, though it does not specify ordering or pagination, which are not critical 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 tool takes no parameters, so the parameter semantics are trivially satisfied. The description does not need to elaborate on inputs.

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

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

The description clearly states the tool's purpose: to list all prompts and return their metadata. It is distinguishable from the sibling get_prompt tool, which retrieves a specific prompt.

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 usage is implied by 'List all prompts', but there is no explicit guidance about when to prefer this over get_prompt or other listing tools. It is adequate but not fully explicit.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds value by explaining the output structure: 'Returns JSON with resource metadata' and the distinction between 'uri' and 'uri_template' fields, which is useful behavioral context beyond what annotations state.

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 with zero filler. The first sentence states the core purpose, and the second adds the crucial detail about output fields. It is front-loaded 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?

With no parameters and an output schema present, the description is complete for an agent to understand when and how to call this tool. It explains what it lists and the format of the output. The presence of an output schema means the description does not need to detail return values further, but it still gives a helpful preview.

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

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

The tool has zero parameters, so the baseline for this dimension is 4. The description does not need to explain parameters because there are none, and the schema confirms an empty object. No additional parameter semantics are required.

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 and target: 'List all available resources and resource templates.' It clearly distinguishes static resources (with 'uri') from templates (with 'uri_template'), which helps differentiate from siblings like read_resource that fetch a specific resource. The verb 'List' and the resource type are 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 clearly implies this tool is for enumeration, but it does not explicitly state when to use it over alternatives or mention any exclusion criteria. It does not say, for example, 'Use this to discover resources before calling read_resource.' While the purpose is clear, the guidance is implicit rather than explicit.

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 read-only, open-world, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond annotations: it says all matching members are returned with specific fields, that common-name matches are disambiguated, and that skipping it produces unrelated results. It does not mention rate limits or auth needs, but those are less relevant for this read-only lookup.

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 trigger in the first sentence, then returns, then ordering rules. It is compact and every sentence serves selection or invocation; no wasted preamble.

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 annotations covering safety and the presence of an output schema, the description supplies everything needed: when to use it, what it returns, why disambiguation matters, and how it fits before ID-filtering sibling tools. No critical selection or invocation detail 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% and the parameter already has an example. The description adds meaning beyond the schema by clarifying that the name query may match multiple members, that common names need disambiguation, and that the result is an integer ID for downstream filtering.

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 and resource: find a Member of Parliament by name and return their integer member_id. It distinguishes itself from sibling tools that filter by member_id and from text-search alternatives, so an agent can select it without opening other 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?

It gives an explicit trigger ('USE THIS TOOL WHEN you have a member's name and need their integer member_id') and an explicit ordering rule ('CALL THIS BEFORE any tool that filters by member_id'), naming three downstream tools. It also warns what happens if skipped, which is strong when-to-use guidance.

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

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

Annotations already cover read-only/idempotent safety, so the description is free to add what they cannot: the vocabulary-independence of the MemberId filter, the expected result volume (~100-200 items for a long debate), and an integrity instruction to report empty results honestly rather than reconstruct quotes from training data. That is substantive behavioral context beyond the structured fields.

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 trigger condition and sibling differentiation are front-loaded, which is exactly right for a selection decision. It runs a little long with some restatement of the member_id filtering point across the opening and closing paragraphs, but each paragraph carries a distinct idea.

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, return-value explanation is unnecessary, and the description still supplies the chaining path, volume expectations, and fallback behavior. Nothing an agent needs to invoke this 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 description coverage is 100%, so both parameters are already fully documented (member_id semantics, debate_ext_id chaining, defaults, volume). The description restates the member_id filtering behavior rather than adding new syntax or format detail, so the baseline 3 applies.

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

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

The description states a specific verb ('get') and resource ('contributions in a debate') and explicitly distinguishes itself from siblings parliament_member_debates and parliament_search_hansard by explaining it filters on MemberId rather than contribution text. An agent can select it correctly without opening the schema.

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 gives an explicit trigger ('USE THIS TOOL WHEN you have a debate_ext_id'), names the alternatives and why they are worse for this job, and lays out the canonical composition chain (find_member → search_hansard/lookup_by_column → this tool). When-not guidance is present via the text-filter caveat.

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?

Despite annotations indicating safe read-only behavior, the description adds valuable behavioral details: empty list is an honest result, cross-resolve happens once per (date, house) group with an extra HTTP, votes_id can be None, and the two ID spaces are distinct. No contradiction with annotations.

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

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

The description is front-loaded with the usage condition and contains well-structured bullet points for the two IDs. It is longer than minimal but every sentence adds meaningful context; 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 tool has an output schema, the description focuses on critical nuances: the possibility of an empty list, the meaning of votes_id, the cross-resolve behavior, and the None case. This provides a complete mental model for correct invocation and interpretation.

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 debate_ext_id, which already includes a detailed description with chaining sources. The tool description itself adds no additional parameter semantics beyond the usage line, 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 retrieves divisions (formal votes) held within a debate. It distinguishes itself from siblings like parliament_get_debate_contributions and votes_get_division by focusing on the debate-level divisions list and explicitly referencing the votes_id linkage.

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 you have a debate_ext_id and want the divisions'. Also provides when-not-to-use context (most debates have no divisions) and directs users to votes_get_division with the votes_id, giving clear alternative and follow-up 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 cover readOnly/idempotent/openWorld, but the description adds substantial context beyond them: the source_code finality scale, the fact that resolution is not gated on publication state, and the diagnostic meaning of empty matches. It stops short of explaining pagination or match ordering, but the behavioral picture is strong.

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 condition and example, then uses tight bullets for return fields and troubleshooting. It is longer than a minimal definition but nearly every line carries actionable information, with only minor redundancy against the schema.

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?

Even though an output schema exists, the description still surfaces the most decision-relevant return fields (contribution_count, source_code) and the interpretation of empty results. Combined with the follow-up pointers, an agent has everything needed to call and act on this tool.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by reinforcing the 'W'-suffixed column convention, the running-volume vs bound-volume trap, and the sitting-date-is-not-a-substitute constraint. It adds real interpretation on top of an already well-documented schema.

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

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

States a specific verb+resource ('resolve a Hansard column citation' via OSCOLA column+volume+house) and complements the title by defining exact input shape. An agent can tell this apart from parliament_search_hansard, which is keyword search rather than citation resolution.

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 an explicit trigger ('USE THIS TOOL WHEN you have an OSCOLA-style Hansard citation'), gives a concrete example, and names follow-up alternatives (read_resource or parliament_get_debate_contributions). It also documents the failure mode for empty matches, which is unusually complete 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 cover safety (readOnly, idempotent, non-destructive), so the bar is lower, and the description adds genuine non-structured context: the verbatim text-body matching semantics, the 3000-char text cap, and the filtering consequence of missing tokens. It does not describe pagination behavior, though the schema's offset field partially covers that.

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 condition, then prerequisites, then the key semantic caveat. Slightly redundant between the two verbatim-search explanations, but every sentence carries routing or behavioral weight.

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

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

Given an output schema exists and annotations cover safety, the description fills every remaining gap an agent needs: the prerequisite call, the text-matching semantics, the 3000-char cap, and the disambiguation from siblings. Nothing required to invoke 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 100%, so the baseline is 3, but the description meaningfully augments the topic parameter by explaining what text is actually searched, what tokens to pass, and what not to pass ('not the bill's name'). This is additive semantic guidance beyond the schema's own prose.

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

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

States a specific verb+resource ('contributions where THAT member used a topic phrase verbatim') and explicitly distinguishes itself from the closest siblings parliament_search_hansard and parliament_get_debate_contributions. An agent can route correctly 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?

Gives an explicit precondition ('WHEN you have a member_id'), a named prerequisite tool to call first (parliament_find_member), and a named alternative with the exact condition that selects it (parliament_get_debate_contributions for vocabulary-independent retrieval). This is textbook when/when-not guidance.

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

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

The description goes well beyond annotations (readOnlyHint, idempotentHint) by detailing pagination behavior (one page of 20, has_more flag), the hard upstream cap on limit (verified live), and the max_description_chars truncation behavior. It also notes that web search returns stale snapshots, adding value. No contradictions with annotations.

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

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

The description is front-loaded with the key usage signal ('USE THIS TOOL WHEN'), then provides necessary operational detail in clearly separated paragraphs. Every sentence serves a purpose—no filler, tautology, or repetition of schema. It is long but information-dense 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?

The tool is moderately complex with 5 parameters and pagination behavior, but the description fully covers when to use it, prerequisite steps, pagination, limits, and the authoritative nature of the data. An output schema exists, so return values needn't be detailed. This is complete for the 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?

The input schema provides 100% parameter coverage with rich descriptions, so the baseline is 3. The description adds practical semantics like how to paginate (offset=offset+returned while has_more is true) and when to raise max_description_chars for forensic work. This is additional guiding context beyond the schema, so a 4 is warranted.

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

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

The description clearly states the tool retrieves registered financial interests for a given member_id, listing specific categories (donations, directorships, land, gifts). It distinguishes from siblings by positioning as the authoritative source for MP/peer financial-interest declarations, and explicitly instructs to call parliament_find_member first, which differentiates it from that lookup 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?

Usage is explicitly conditioned: 'USE THIS TOOL WHEN you have a member_id and need their registered financial interests.' It provides a clear prerequisite (call parliament_find_member first), directs away from web search due to stale data, and gives pagination guidance for prolific members. This is excellent 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 declare readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false. The description adds behavior beyond that: it sweeps /search/Debates.json with pagination, states the hard cap semantics, discloses the rate limit ('1000 req/5min'), notes that by_party and top_contributors are deliberately omitted due to upstream limitations, and confirms 'no LLM, no editorial labels'. The omission disclosure is unusually valuable context.

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

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

Front-loaded with the WHEN clause; each sentence carries a distinct point (trigger, mechanics, follow-up, member-facet caveat, authority claim). The member-facet note is a bit long but earns its place by explaining an omission. Some repetition between the title and 'authoritative source' sentence, but overall tight.

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?

All key facets of the tool's behavior are covered for an agent: when to use it, what it aggregates, the sweep mechanism and cost, the follow-up path, and known limitations (missing member-level facets). With an output schema present, no return-value explanation is required, and nothing material is missing for correct 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?

Schema description coverage is 100%, so the schema already documents all five parameters, including defaults, enums, and the rate-limit note in max_debates_scanned. The description briefly contrasts topic semantics with parliament_search_hansard.query (debate-level metadata matching vs body text), which is a small addition, but mostly repeats what the schema already says. 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 title and body state a specific verb (aggregate) and resource (Hansard debate-level signals on a topic), and it explicitly differentiates itself from text-search siblings (parliament_search_hansard) by describing the facet-aggregation output (by_house, by_year, by_section). The mention of 'authoritative source for UK Hansard corpus-level signals' anchors the 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 opening 'USE THIS TOOL WHEN...' clause states the trigger condition, and it names a clear follow-up ('pass debate_ext_id into parliament_get_debate_contributions') plus an alternative for member-level queries (hansard://debate/.../header or parliament_member_debates). It doesn't fully name what this tool is not for versus parliament_search_hansard, but the WHEN clause plus alternatives is strong.

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 safety (readOnly, idempotent, non-destructive, openWorld), yet the description adds real operational disclosure beyond them: the independent corpus envelope may fail with one bounded retry, contributions then return enrichment_status='degraded' with a warning, and 'omitted corpus totals and previews must not be inferred' — a critical anti-hallucination constraint. It also states that envelope fields are source-backed only when complete.

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 a capitalized trigger, then organized into returns, degraded-mode caveat, follow-up calls, exclusions, pagination, and source authority. Nearly every sentence earns its place for a routing-critical tool, though the 'bill title' clause in the opening sentence is a wasteful inaccuracy and the closing source-authority note partially restates the degraded-mode paragraph.

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

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

Output schema exists, so return values need not be detailed, yet the description still names the citation fields and explains the degraded envelope path — more than adequate for a 9-parameter tool. The gap is that nothing tells the agent the relationship between house/member_id/date filters and the query semantics (e.g. whether filters can be combined with free text), and the bill-title claim muddies the calling recipe.

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 per-parameter docs are already excellent (text_mode cap sizes, contribution_type section meanings, member_id integer requirement), so the baseline is 3. The description only adds 'limit + offset honour the upstream paginated endpoint' and does not touch text_mode, contribution_type, or the date filters — marginal additive value over the schema.

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

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

States a specific verb and resource ('searching Hansard') and enumerates the retrieval axes: topic, bill title, text phrase, with the return payload named (contributions with citation-grade metadata). The one flaw is that the opening line advertises 'bill title' searching, which the query parameter description explicitly warns 'often DON'T match' — an internal tension an agent must resolve by reading the schema.

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 ('searching Hansard by topic... text phrase', 'DO NOT text-search by member name'), names the alternative chain parliament_find_member → parliament_get_debate_contributions as the canonical path for named members, and points to parliament_policy_position_summary for breadth and parliament_get_debate_contributions for whole-debate retrieval. Both positive routing and a negative exclusion are stated.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the bar is lower. The description adds valuable context about return fields (title, state, signature count, dates) and the authoritative source, but does not disclose behavioral details like pagination or rate limits.

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

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

The description is appropriately sized, with the key usage directive front-loaded. Each sentence serves a purpose: usage, returned data, filtering, and authoritative source. No wasted words.

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

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

Given the tool has a rich output schema and fully described parameters, the description covers the essential usage context well. It does not explain pagination, but the offset parameter schema already handles that, and the output schema likely documents the return shape. Slight gap on the debated state discrepancy.

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 mentions filtering by state but inconsistently lists 'debated' as an option while the schema enum only allows 'open', 'closed', and 'all', which could mislead. It does not add significant meaning beyond the schema's already descriptive parameter fields.

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 ('search') and resource ('UK Parliament petitions') with clear scope ('by keyword or topic'). It distinguishes itself from sibling tools like parliament_search_hansard and bills_search_bills by focusing on petitions 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?

The description opens with 'USE THIS TOOL WHEN searching UK Parliament petitions by keyword or topic,' providing explicit usage context. However, it does not explicitly mention when not to use it or name alternative tools, falling short of the highest bar.

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 operation as read-only, idempotent, non-destructive, and open-world. Beyond that, the description adds useful behavioral detail: content is returned as a string, binary content is base64-encoded, and rejected URIs should be handled by following the named source-specific tool rather than treating the URL as retrieved evidence.

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 purpose, followed by clear USE WHEN, return-value, and post-call guidance. Every section contributes directly to correct tool selection and invocation, with no wasted text.

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

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

The tool has a simple one-parameter schema, full schema coverage, an output schema, and annotations covering safety and identity behavior. The description completes the picture by explaining accepted URI types, exclusions, return encoding, and error-handling guidance for rejected URIs.

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

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

Schema coverage is 100%, so the schema already defines the single uri parameter and gives examples. The description adds meaningful semantics by clarifying that the URI must be a registered server resource URI rather than an ordinary web URL and by naming the relevant schemes and fallback tool.

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 and resource: read a registered server resource URI, explicitly not an ordinary web URL. It names the accepted URI schemes and distinguishes this tool from source-specific siblings such as hmrc_get_manual_page, so an agent can identify its role immediately.

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 gives explicit USE WHEN guidance tied to judgment://, legislation://, hansard://, and server:// URIs returned by the server. It also states when not to use it for https:// URLs and directs the agent to the source-specific alternative with a concrete example.

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 (read-only, idempotent), the description discloses a critical behavioral trait: voter lists are truncated to 100 per side while total counts remain accurate. This level of transparency helps agents set expectations and avoid misinterpreting truncated data. No contradiction with annotations.

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

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

The description is highly concise, front-loaded with an explicit 'USE THIS TOOL WHEN' directive, and packs essential information (purpose, input prerequisites, truncation caveat, chaining) into two sentences. Every sentence adds value, and the capitalization draws appropriate attention.

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 only two parameters and an existing output schema, the description covers all critical aspects: what the tool does, when to use it, key limitations (truncation), and how to obtain inputs. 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?

The input schema already provides full coverage (100%) with descriptions for both parameters, including the source of division_id. The description only restates 'division_id + house' without adding further semantic detail, so it meets the baseline but does not elevate parameter understanding.

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

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

The description clearly states a specific action—retrieving the full member-by-member voting record for a division—and immediately distinguishes itself from sibling search and debate tools. The resource (division_id + house) is explicit, and the chaining reference to votes_search_divisions and parliament_get_debate_divisions further differentiates it.

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

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

The description explicitly tells agents when to use this tool ('USE THIS TOOL WHEN you have a division_id + house'), and provides guidance on how to obtain the ID via sibling tools. It also clarifies the chaining workflow, though it could be more explicit about when not to use it; still, the guidance is strong and actionable.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavior beyond annotations: it returns one page of summaries, includes a `total` count, explains pagination with offset=offset+returned, and describes what is not included (full member lists). It also notes the authoritative source, which helps set expectations.

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

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

The description is compact and every sentence earns its place: the when-to-use directive, the return shape, pagination logic, the next-step linkage, and the source authority. The all-caps phrases are intentional emphasis for an agent, and the paragraph is front-loaded with the most actionable guidance.

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

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

With an output schema present and 100% parameter schema coverage, the description only needs to supply usage context and behavior not already in structured fields. It does so thoroughly, covering search scope, pagination, what the response contains, and the follow-up tool to use. Nothing an agent needs to call this tool 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 description coverage is 100%, so the schema already documents every parameter. The description reinforces that search can be by topic, date, or member, but doesn't add new semantic details beyond what the schema provides. Per the baseline rule, 3 is appropriate.

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

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

The description opens with an explicit directive: 'USE THIS TOOL WHEN searching Commons or Lords formal votes by topic, date, or member.' This names the verb (search), the resource (formal votes), and the filtering dimensions. It is clearly distinguished from the sibling votes_get_division by specifying that this returns summaries and that the full voter lists are obtained via the follow-up call.

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 when-to-use statement and instructs the agent to re-call with offset while has_more is true, and to pass division_id + house into votes_get_division afterward. It doesn't explicitly exclude alternatives like parliament_search_hansard or parliament_get_debate_divisions, but the formal-votes scope and the named follow-up make the intended usage clear.

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