UK Legal Research

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

Annotations already indicate readOnlyHint, idempotentHint, etc. The description adds value by specifying returned fields (sponsors, stage, summary, royal assent) and explaining summary truncation behavior with max_summary_chars and the summary_truncated check, beyond what annotations provide.

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

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

The description is concise, structured with clear sections (USE THIS TOOL WHEN, AFTER calling), and no redundant sentences. Every sentence provides essential 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?

Given the presence of an output schema, the description appropriately covers key return fields and truncation behavior. All necessary context for tool selection and usage is present.

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

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

With 100% schema description coverage, the description still adds meaningful context: bill_id originates from bills_search_bills, and max_summary_chars has practical advice on raising for substantive bills and checking truncation.

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

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

The description explicitly states the tool's purpose: to get full bill detail when you have a bill_id from bills_search_bills. This clearly distinguishes it from sibling tools like bills_search_bills.

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 context (having bill_id from search results) and suggests follow-up actions like parliament_search_hansard for debates and bills_search_bills for adjacent bills, effectively guiding the agent on when to use alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds that it returns a paginated page of bill summaries (title, current stage, Act status), which is useful behavioral context. It does not contradict annotations.

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

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

The description is concise, consisting of four sentences that are front-loaded with the usage instruction, then output summary, next step, and authority statement. Every sentence adds value with 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 and nested objects, the description covers purpose, output format (summaries), follow-up action, and authority. It omits pagination details (handled in schema) and error handling, but is sufficiently complete for an AI agent to use effectively.

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 decent descriptions for each parameter. The description merely lists the filter types (keyword, session, house, legislative stage) that map to schema parameters, adding little beyond what the schema already provides. Baseline score of 3 is appropriate.

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

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

The description starts with 'USE THIS TOOL WHEN searching UK parliamentary bills by keyword, session, house, or legislative stage,' which provides a specific verb, resource, and filtering criteria. It explicitly distinguishes from the sibling 'bills_get_bill' for detailed follow-up, and asserts authority, leaving no ambiguity about its purpose.

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

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

The description clearly states when to use the tool (searching bills) and directs users to call 'bills_get_bill' with a bill_id for full detail. While it does not explicitly mention when not to use it or contrast with other search tools like 'legislation_search', the guidance is sufficient and context-rich.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that the tool returns a list of {eId, snippet, match} hits, small per-paragraph snippets centred on the match, and explains the pattern fallback behavior (regex to literal substring). This provides useful additional context beyond annotations.

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

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

The description is concise and well-structured: it starts with the usage directive, explains what is returned, gives use cases, and contrasts with a sibling tool. Every sentence adds value with no redundancy.

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

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

Despite the complexity of a regex search tool with multiple parameters and an output schema, the description covers all essential aspects: when to use, what it returns, how to follow up, and the fallback behavior. The presence of an output schema reduces the need to detail return values, but the description still concisely summarizes the key fields.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds context like the return format and usage pattern, but does not substantially enhance parameter meaning beyond the thorough schema descriptions (e.g., slug format, pattern behavior). The fallback behavior is already in the schema's pattern 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 starts with 'USE THIS TOOL WHEN you have a judgment slug and want to find paragraphs whose text matches a pattern,' clearly stating the verb (search) and resource (within a UK court judgment). It distinguishes from sibling tool judgment_get_index by noting that the latter is for paragraph-number navigation by eId.

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

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

The description gives explicit when-to-use guidance ('USE THIS TOOL WHEN you have a judgment slug'), provides use cases like searching for 'negligence', and instructs users to read full paragraphs via judgment_get_paragraph after calling. It also specifies when not to use it (for paragraph navigation, use judgment_get_index instead).

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 set readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds crucial behavioral details: it returns paginated summaries with specific fields, describes coverage (from early 2000s), and discloses that date filters may be silently ignored by the upstream endpoint. This greatly aids the agent in understanding tool behavior and limitations.

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 paragraphs: purpose, return format, after-use steps, narrowing advice, coverage, and warnings. Every sentence serves a purpose. It is front-loaded with the primary use case. Despite length, it is efficient and 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 complexity (search with multiple filters, many sibling tools, output schema), the description is exceptionally complete. It covers what the tool does, how to use it, what to expect from results, limitations, integration with other tools, and even anti-patterns. The presence of an output schema does not reduce the need for this rich context.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds nuance beyond the schema: it notes that judge filter should not include honorific suffixes, and that date filters are unreliable. It also summarizes the filter types. Thus, it adds value beyond the schema 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 'USE THIS TOOL WHEN searching UK case law by party names, court, judge, date, or free-text query.' It clearly identifies the verb 'search' and the resource 'UK case law'. It distinguishes from siblings by detailing subsequent steps (e.g., using judgment_get_header, citations_resolve) and by noting that this tool returns paginated summaries, not full content.

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

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

The description provides explicit guidance on when to use this tool, including narrowing strategies (e.g., 'narrow with court + year filters before grep-iterating') and handling older authorities. It also explicitly warns against supplementing with web search, stating 'do not supplement'. This helps the agent decide when to use this tool vs alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idlempotentHint=true, and destructiveHint=false. The description adds value by explaining the tool fetches XML, parses OSCOLA citations, and returns grouped, deduplicated, sorted results. It does not contradict annotations.

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

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

The description is concise with no wasted words. It front-loads the purpose with 'USE THIS TOOL WHEN', then provides process details and follow-up instructions in a well-structured manner.

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 (not shown but mentioned in context), the description does not need to detail return values. It covers input requirements, process logic, and post-call actions, making it complete for an agent to use correctly.

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

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

Schema coverage is 100% for the single parameter case_uri, so baseline is 3. The description adds extra context: 'Use the 'uri' field from case_law_search results — not the full URL. Do not include the 'https://caselaw.nationalarchives.gov.uk/' prefix.' This enhances clarity beyond the schema.

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

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

The description starts with 'USE THIS TOOL WHEN you have a judgment slug and want to map every citation it makes', providing a specific verb and resource. It distinguishes the tool from siblings like citations_resolve and citations_parse by stating its comprehensive citation mapping role.

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

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

The description explicitly states when to use the tool (with a judgment slug) and instructs the agent to pass individual citations to citations_resolve afterwards for confirmation and canonical URL retrieval. This provides clear chaining guidance and differentiation.

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

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

The description discloses key behaviors: pure regex parsing by default, optional LLM-based disambiguation, URL resolution when possible, and the limitation that it does not confirm document existence. This 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?

The description is well-structured with a clear opening, bullet-like list of citation types, concise explanations of parsing and disambiguation, and a concluding instruction. Every sentence adds value without redundancy.

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

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

Given the tool's complexity and the presence of an output schema, the description covers purpose, input, behavior, and post-processing steps. It also references the sibling tool for resolution, making it fully informative for an AI agent.

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

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

The description adds meaning to the input schema parameters: it explains the disambiguate parameter with clear guidance on when to use it, and reiterates supported citation types. This compensates for the schema's concise descriptions.

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

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

The description clearly states the tool's purpose: extracting and classifying OSCOLA citations from free text. It lists specific citation types and distinguishes itself from the sibling tool citations_resolve by noting that parsing does not verify document existence.

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

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

The description explicitly tells when to use the tool ('USE THIS TOOL WHEN you have free text...') and provides guidance on using disambiguate optionally. It also instructs to follow up with citations_resolve for verification, offering clear usage context.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds significant detail: live HTTP HEAD check for neutral citations, confidence=0.0 on TNA non-200, ValueError on unrecognized input, and a strong warning against using low-confidence results. 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 a capitalized directive. All sentences are substantive, covering purpose, behavior, failure modes, and warnings. While longer than minimal, it efficiently conveys essential information without verbosity.

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 (1 param, output schema present, annotations covering safety), the description is complete. It addresses when to use, how it works (including live HTTP check), failure modes, and user guidance. No gaps remain for an agent to misuse the tool.

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

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

Schema coverage is 100% with a clear description and example for the citation parameter. The tool description repeats this but adds context about resolution behavior. Since schema does most of the work, baseline is 3; description adds minimal extra semantic value.

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

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

The description clearly states the verb 'resolve' and the resource 'single OSCOLA citation'. It provides specific context: 'USE THIS TOOL BEFORE constructing an OSCOLA citation string... OR when you have a citation and want to confirm it points at a real document.' This distinguishes it from siblings like citations_parse (likely parse only) and emphasises the resolution aspect.

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 guidance is given (before formatting, for verification). It also tells when NOT to use: if the tool fails, do not manufacture a citation. It warns against common fabrication errors and advises to ask for source URL. 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 declare readOnlyHint, idempotentHint, destructiveHint. Description adds that it fetches detail and member list in parallel, a key behavioral trait 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, no fluff, front-loaded with the usage instruction. Every sentence provides necessary information.

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

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

With only one parameter, output schema present, and rich annotations, the description adds relevant context about parallel fetching and follow-up action, making it complete for a simple getter tool.

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

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

Schema description already covers the parameter source ('Committee ID from committees_search_committees results.'). Description does not add additional meaning beyond that.

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

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

Clearly states to use when having a committee_id to get metadata and current membership. Distinguishes from sibling tools like committees_search_committees and committees_search_evidence.

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

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

Explicitly states when to use ('USE THIS TOOL WHEN you have a committee_id') and provides a clear next step (use committees_search_evidence). No exclusion of alternatives needed as context is clear.

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

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

Annotations already indicate readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds that it returns committee summaries with specific fields (name, house, active status, ID) and includes a note about the default limit covering all active committees. This is sufficient behavioral context.

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

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

The description is two sentences long, front-loaded with the usage trigger, and contains zero wasted words. It efficiently conveys purpose, return, and next steps.

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

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

Given the presence of a complete output schema (not shown but indicated), the description adequately explains the return value (committee summaries) and connects to related tools. No gaps are evident for the tool's intended use.

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

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

The input schema has 100% description coverage for all parameters. The description only briefly mentions 'by name, house, or active status', which aligns with parameters query, house, and active_only. This adds marginal value beyond the schema, so a 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 searches or lists UK parliamentary select committees by name, house, or active status. It distinguishes itself from sibling tools like committees_get_committee and committees_search_evidence by specifying that it returns summaries and should be used first for discovery.

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

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

The description explicitly states when to use ('USE THIS TOOL WHEN searching or listing...') and provides explicit follow-up steps: pass committee_id to committees_get_committee or committees_search_evidence. This gives clear guidance on workflow 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?

Adds behavioral details beyond annotations: returns one page, caps on titles and witness lists, and pagination logic. Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description supplements with useful operational 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?

Two highly informative paragraphs. Every sentence adds value: first sentence states purpose, second sentence explains pagination and caps, third sentence reinforces pagination, fourth establishes authority. 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?

Covers pagination, caps, and data source. With an output schema present, return value details are not needed. Lacks error handling or rate limits, but for a read-only paginated tool with annotations, it is sufficiently complete.

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

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

Schema already describes all 5 parameters with 100% coverage. Description adds context: explains that limit splits when evidence_type='both' and that max_title_chars default prevents context blow-up. Adds value beyond schema.

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

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

The description clearly states when to use this tool ('when you have a committee_id and want the oral and written evidence submitted to it'), specifies the verb 'search' and resource 'evidence', and is distinguishable from sibling tools like committees_search_committees.

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 the condition for use (having a committee_id) and provides clear pagination instructions ('re-call with offset=offset+returned while has_more is true'). No explicit when-not-to-use, but context from sibling names implies differentiation.

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. The description adds behavioral context about the return format (JSON with messages array) and that arguments are a dict, which is beyond the annotations.

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

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

The description is concise (3 sentences) and front-loaded with the main action. Every sentence adds necessary information without redundancy.

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

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

Given the presence of an output schema, the description sufficiently covers the tool's behavior: what it does, input parameters, and the structure of the return value. No gaps remain.

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

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

Schema coverage is 100%, and the description adds value by specifying that arguments should be provided as a dict mapping names to values. It also clarifies that arguments are optional, reinforcing 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 'Get a prompt by name' and specifies the return format (rendered prompt as JSON with messages array). It distinguishes from sibling 'list_prompts' which likely lists prompts, so purpose is unambiguous.

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

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

The description provides clear usage context (get a prompt by name with optional arguments) but does not explicitly state when not to use it or mention alternatives. The sibling 'list_prompts' exists, but no direct guidance is given.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses that the tool connects to the HMRC sandbox by default, requires HMRC_CLIENT_ID and HMRC_CLIENT_SECRET env vars, and raises an error if credentials are missing. It also warns against inferring status. No contradictions with annotations.

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

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

The description is concise (6 sentences) and well-structured. The first sentence provides immediate usage guidance, followed by return fields, then setup instructions. Every sentence adds value with no repetition 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 the tool's simplicity (single parameter, output schema exists), the description covers all necessary context: usage trigger, return fields, environment configuration, and error conditions. It is complete for an agent to select and invoke the tool correctly.

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

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

The single parameter (vrn) is fully described in the input schema (100% coverage), including format, length, and GB prefix handling. The description reiterates the 9-digit requirement and prefix stripping but does not add new semantic meaning beyond the schema.

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

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

The description clearly states the tool's purpose: to check a business's Making Tax Digital VAT mandate status using a 9-digit VAT Registration Number. It specifies the resource ('MTD status') and the action ('check'), and distinguishes from sibling tools like hmrc_get_vat_rate and hmrc_search_guidance by focusing on MTD compliance.

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

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

The description explicitly states when to use the tool ('when you have a 9-digit VAT Registration Number and need that business's Making Tax Digital VAT mandate status'). It also provides setup guidance (sandbox vs production, required env vars) and warns about credential errors. It does not explicitly mention when not to use or name alternatives, but the context is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, establishing safety. The description adds value by revealing the tool uses a static lookup table with a specific date, and warns that rates may have changed, which is helpful context beyond annotations.

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

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

Three short sentences: the first gives a clear usage directive, the second lists return values, the third provides a critical caveat. No redundant information, every sentence serves a purpose.

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

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

Given the tool's simplicity, the description covers usage criteria, return format (rates, date, conditions), critical temporal limitation, and a fallback behavior. An output schema exists, so return value explanation is not needed. Completely sufficient 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?

Schema description coverage is 100% for the single parameter 'commodity_code', including examples and constraints. The description does not add new semantic information beyond the schema, so it meets the baseline 3.

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

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

The description starts with 'USE THIS TOOL WHEN' and clearly states the tool's purpose: to get the VAT rate category for a UK commodity or service description. It specifies the exact rates returned and distinguishes from the sibling tool hmrc_search_guidance for verification.

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

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

Explicitly states when to use the tool (when you have a commodity/service description) and provides a clear alternative (hmrc_search_guidance) for time-sensitive or updated advice. The limitation about the static lookup table current as of Nov 2023 is highlighted.

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, destructiveHint. The description adds return fields (titles, URLs, summaries, dates) and asserts authority as 'Authoritative source for current HMRC tax guidance', which is useful context beyond annotations.

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

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

The description is concise (3 sentences), front-loaded with purpose, and every sentence adds value. No wasted words.

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

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

Given the output schema exists and parameter count is low, the description is sufficiently complete. It covers what is searched, what is returned, and why it's authoritative.

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 description only adds minor context (e.g., 'filtered to HMRC publications', example queries). Baseline 3 applies; no significant added semantics.

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

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

The description explicitly states the verb 'search' and the resource 'HMRC tax guidance on GOV.UK', and distinguishes it from siblings by specifying HMRC-specific content.

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

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

It provides clear when-to-use guidance ('USE THIS TOOL WHEN searching GOV.UK for HMRC tax guidance') and explicitly warns against using web search for this purpose ('do not supplement'), offering clear alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds behavioral context beyond annotations by specifying the kind of metadata returned and its authoritative nature, without contradicting the annotations.

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

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

Two sentences, front-loaded with 'USE THIS TOOL WHEN', no redundant words. Every sentence provides essential information about purpose, usage, and workflow.

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

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

For a simple tool with one parameter, rich annotations, and an output schema, the description is complete. It covers when to use, prerequisites (slug from case_law_search), and relationship to sibling tools. No gaps.

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

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

The schema already provides a detailed description of the slug parameter with examples (100% coverage). The description adds value by explaining where to obtain the slug (from case_law_search), enhancing usage context beyond the schema.

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

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

Description clearly states it retrieves metadata (parties, judges, neutral citation, court, dates) given a judgment slug. It distinguishes from sibling tools like judgment_get_index and judgment_get_paragraph by specifying its role in the workflow.

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

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

Explicitly instructs when to use ('USE THIS TOOL WHEN you have a judgment slug and need metadata'), provides a clear workflow (call case_law_search first, then judgment_get_index, then judgment_get_paragraph), and notes it is the authoritative source for UK judgment metadata.

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, destructiveHint false. The description adds behavioral context: returns a navigation index with eId and preview line per paragraph. This is sufficient beyond annotations but lacks detail on 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?

Description is concise (two sentences), front-loaded with 'USE THIS TOOL WHEN', and structured in logical steps. Every sentence provides essential guidance with no fluff.

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

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

Given the tool's low complexity (1 parameter, clear annotations, output schema present), the description sufficiently covers what the tool does, inputs, outputs, and usage workflow. No gaps identified.

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

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

Only one parameter (slug) with 100% schema coverage and a clear schema description. The description does not add meaning beyond 'the slug is used to get the index', which is already implied. 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?

Description explicitly states the verb 'get' and resource 'judgment paragraph index', and specifies the output 'eId + preview line for every paragraph'. It clearly differentiates from siblings by mentioning judgment_get_paragraph and case_law_grep_judgment as subsequent steps.

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 'USE THIS TOOL WHEN' condition (having a judgment slug wanting navigation index), instructs to call case_law_search first, and describes what to do with the returned eIds (use judgment_get_paragraph or case_law_grep_judgment). This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already confirm safe read operation; description adds typical output token range (400–1700) and that it returns XML content. Could mention potential errors but sufficient.

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

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

Three concise sentences, front-loaded with usage guidance. Every sentence adds value.

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

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

Given output schema exists and annotations cover safety, description provides essential input context, prerequisites, alternatives, and typical output size. Complete for this tool.

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

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

Schema covers both parameters fully. Description adds practical context on obtaining eId from judgment_get_index, which helps users provide correct parameter values.

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

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

Clearly states the tool retrieves a judgment paragraph given slug and eId. Differentiates from siblings by referencing judgment_get_index and case_law_grep_judgment.

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

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

Explicitly specifies when to use (have slug + eId) and provides prerequisite (call judgment_get_index) and alternative (case_law_grep_judgment).

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. The description adds critical behavioral details: content truncation at max_chars with a content_truncated response field, a warning to check extent, and note that schedules are not supported. 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 well-structured with bullet points and front-loaded purpose. While slightly verbose for a simple tool, every sentence earns its place by providing actionable guidance or caveats. No redundancy.

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

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

Given the complexity (legislation types, extent, truncation) and the presence of an output schema, the description fully covers what the tool returns (text, extent, in-force status, prospective flag), mentions truncation behavior, explicitly warns about checking extent, and notes unsupported schedules. It is complete for effective use.

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 adds meaningful context beyond the schema: for 'type' it instructs to use value from legislation_search results, for 'section' it clarifies to use numeric part only, and for 'max_chars' it gives usage guidance (raise for definition sections). This adds value.

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

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

The description begins with 'USE THIS TOOL WHEN you have a known Act / SI and want the parsed text of a specific section' which clearly states the verb (get parsed text) and resource (section of an Act/SI). It also distinguishes itself from the sibling tool 'read_resource' by contrasting parsed structured response vs raw XML.

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

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

The description explicitly states when to use this tool (when you have a known Act/SI and want parsed text with metadata) and provides an alternative (read_resource for raw XML). It also includes a strong directive to always check 'extent' to avoid legal research errors, but does not exhaustively list when not to use it.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds pagination behavior (offset/limit, has_more, total_items), example output, and correct usage of numeric identifiers. No contradiction.

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

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

Description is well-structured with use-case, output description, example, pagination, and alternative. Slightly long but front-loaded and organized. Could be slightly more concise.

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

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

Given presence of output schema, description covers required context: when to use, what is returned (structural elements, example), pagination, and alternative approach. No gaps identified.

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

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

Schema has 100% description coverage, so baseline is 3. Description adds context: explains type derivation from search results, usage of offset/limit with example, and warning about numeric ID format. Adds value beyond schema.

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

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

The description clearly states the tool returns structural table of contents for known Acts/SIs, distinguishes from 'legislation_get_section' by specifying full text retrieval, and provides an example. The purpose is specific 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?

Explicitly says 'USE THIS TOOL WHEN you have a known Act / SI and want the structural table of contents'. Provides an alternative (read_resource) and explains when to use each. Also mentions pagination for large statutes.

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, destructiveHint=false, so the safety profile is clear. The description adds behavioral context: it returns ranked results, includes next_steps hints (toc URI, section template), and specifies filter discipline (exact-match). This adds value beyond annotations without contradicting them.

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

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

The description is concise and well-structured. It front-loads the key purpose ('USE THIS TOOL WHEN'), then organizes return info, filter discipline, authoritative source. Every sentence serves a purpose, no filler. It's easy to scan.

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

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

Given the tool's complexity (5 parameters, filtering, chaining), the description is comprehensive. It covers when to use each filter, the return structure (including next_steps), fulltext vs title search, and proper chaining to other tools. Output schema exists but description needn't cover that.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra context beyond schema descriptions: e.g., for `year` it explains the pitfall of guessing and provides a better workflow; for `type` it says 'Exact-match — omit if you don't already know whether you're looking for an Act vs an SI'; for `fulltext` it gives examples. This adds significant value.

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

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

The description clearly states the tool is for searching UK Acts and Statutory Instruments by title, phrase, or full-text. It names the specific resource ('UK Acts and Statutory Instruments') and uses a strong verb ('search'). It distinguishes from sibling tools like `bills_search_bills` or `case_law_search` by specifying the domain (UK legislation) and the types of documents.

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 (searching UK Acts/SIs), explicit when-not-to-use guidance for filters ('type` and `year` are exact-match – omit if unsure'), and explicit chaining instructions ('AFTER calling, chain to legislation_get_toc then legislation_get_section'). It warns against guessing years and advises on fulltext usage.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false. The description adds that it returns JSON with metadata, which is useful context beyond the annotations.

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

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

Two sentences, front-loaded with the main action, no wasted words. Efficient and clear.

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

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

With no parameters, rich annotations, and an output schema, the description fully covers the needed context. It is complete for this simple tool.

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

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

No parameters exist, so schema coverage is 100%. The description adds no parameter info, which is appropriate because none is needed. Baseline 4 applies.

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

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

The description clearly states 'List all available prompts' with a specific verb and resource. It effectively distinguishes from the sibling 'get_prompt' by implying a collection versus a single item.

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

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

The description implies when to use (to list all prompts) but lacks explicit guidance on alternatives. It does not mention when not to use or compare with 'get_prompt' or 'list_resources'.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds value by explaining the response format (JSON with 'uri' for static resources and 'uri_template' for templates), which is beyond what annotations provide.

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

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

The description is concise, comprising two clear sentences. The key action and resource are front-loaded, with no unnecessary information.

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

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

Given zero parameters and the presence of an output schema, the description fully covers the tool's purpose and distinguishes between resource types. It provides sufficient context for an AI agent to understand what the tool does and what it returns.

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

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

The input schema has zero parameters, so schema description coverage is 100%. The description does not need to explain parameters; it adds value by describing the output structure, which is relevant for tool usage.

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

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

The description clearly states 'List all available resources and resource templates,' specifying the verb (list) and resource type. It distinguishes between static resources and templates, differentiating from sibling tools like list_prompts which list prompts instead.

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

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

The description does not explicitly state when to use this tool versus alternatives. While it implies use for obtaining a full list of resources, it lacks guidance on when not to use it or mention of sibling tools like search functions.

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. The description adds behavioral context beyond annotations: it returns all matching members (multiple results), not just one; includes disambiguation example ('Lord Smith' returns multiple peers). 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?

Description is well-structured: starts with a bold instruction ('USE THIS TOOL WHEN'), then lists return fields, then provides usage guidance. No wasted words, every sentence adds value. Concisely covers purpose, usage, and disambiguation.

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

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

Given the tool's simplicity (1 parameter, low complexity), the description is complete. It explains the return value, workflow (call before ID-based filters), and disambiguation. An output schema exists (mentioned in context signals), so description doesn't need to detail return structure. All necessary information is present.

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

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

Schema description coverage is 100% (the 'name' parameter has a clear description with examples). The description adds meaning beyond schema: it explains that the result includes an integer id, party, constituency, etc., and that partial names are valid. It also shows disambiguation behavior.

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: given a member's name, return their integer member_id. It specifies the return fields (id, party, constituency, house, current-sitting status) and disambiguation for common names. This is specific and distinguishes it from siblings like parliament_search_hansard.

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

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

The description explicitly says 'USE THIS TOOL WHEN you have a member's name and need their integer member_id.' It instructs to call this before tools that filter by member_id, listing specific sibling tools (parliament_get_debate_contributions, parliament_member_debates, parliament_member_interests). It warns against skipping this step and mentions the Pannick case to emphasize the need.

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=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: without member_id returns all contributions (~100-200 items), and instructs to report empty results honestly without reconstructing quotes. This goes beyond annotations without contradicting them.

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

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

The description is well-structured with a clear 'USE THIS TOOL WHEN' opening, canonical path explanation, typical chain, and notes on empty results. While slightly verbose, every sentence earns its place and the most critical information is front-loaded. Minor redundancy in the chain description reduces conciseness slightly.

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 (optional filtering, integration with other parliamentary tools), the description is comprehensive. It covers when to use, when not to use, typical usage patterns, and error handling (empty results). With full schema coverage and annotations, no significant gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning: explains that member_id filters by member regardless of vocabulary, typical debate size, and the origin of debate_ext_id from other tools. This enriches the schema's descriptions and aids correct parameter usage.

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

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

The description clearly states the tool's purpose: 'USE THIS TOOL WHEN you have a debate_ext_id and want verbatim contributions, optionally filtered to one member.' It uses a specific verb ('get') and resource ('contributions in a debate'), and distinguishes from siblings by contrasting with text-search tools like parliament_member_debates and parliament_search_hansard.

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

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

Explicitly states when to use ('USE THIS TOOL WHEN you have a debate_ext_id...') and provides alternatives: text-search tools for text-based filtering vs. this tool for member-based filtering regardless of vocabulary. Includes a typical chain for tool composition, giving clear guidance on integration with other tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description adds valuable context beyond these: it explains that empty results are honest and expected, and describes typical scenarios where divisions occur. This enhances transparency about the tool's behavior without contradicting 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 instruction in the first sentence, followed by concise context about when divisions occur and the meaning of empty results. It contains no wasted words and is efficiently structured for quick understanding.

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 tool with one parameter and an output schema (not shown but indicated), the description covers all necessary context: when to use, what to expect, typical cases, and how to interpret empty results. It is complete for an AI agent to use correctly.

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

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

Schema coverage is 100% with a detailed description for the single parameter debate_ext_id (including chaining instructions). The description does not add additional semantic meaning beyond what is already in the schema, which is thorough. Therefore, baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'USE THIS TOOL WHEN you have a debate_ext_id and want the divisions (formal votes) held within it.' It specifies the verb 'Get Divisions' and the resource 'Debate', distinguishing it clearly from sibling tools like parliament_get_debate_contributions.

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 provides when-to-use guidance: 'USE THIS TOOL WHEN you have a debate_ext_id and want the divisions...' and also explains when not to expect results: 'Most debates contain no divisions — Business of the House sittings, statements, urgent questions, debates without a vote.' It further clarifies that an empty list is not a failure.

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

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

The description adds behavioral context beyond the annotations (readOnlyHint, idempotentHint, etc.). It explains that the tool resolves citations and requires the volume number, and clarifies that the date is not an alternative. There is 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 very concise: two short paragraphs. The first gives a clear imperative usage directive with an example. The second provides technical nuance about the volume requirement. No unnecessary words.

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

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

Given that annotations cover safety and output schema exists, the description is complete: it covers purpose, usage, parameters, and post-call actions. No gaps remain.

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

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

The schema has 100% description coverage for parameters, but the description adds significant meaning: it explains the OSCOLA format, column suffix (e.g., 'W' for written answers), and the necessity of volume number. This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: resolving an OSCOLA-style Hansard citation (column + volume + house) to find the debate. It provides an example and distinguishes itself from sibling tools like parliament_get_debate_contributions by specifying that after calling this tool, one should use another tool to read contributions.

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

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

The description explicitly says 'USE THIS TOOL WHEN' and gives an example. It also provides crucial guidance that the sitting date is NOT a substitute for volume number, which is verified live. Furthermore, it advises on subsequent steps (using read_resource or parliament_get_debate_contributions).

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=true, idempotentHint=true, destructiveHint=false. Description adds behavioral context: text-body search matches contributions containing the phrase, member must have used the phrase verbatim, text field capped at 3000 characters. No contradiction with annotations.

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

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

The description is well-structured with bold headings and bullet-like clarity, front-loading the core use case. Every sentence adds value, but it is somewhat long. Minor deduction for length, but overall efficient.

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

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

Given the presence of an output schema, the description does not need to explain return values. It fully covers purpose, guidelines, parameter semantics, and behavioral details including the text cap. It also differentiates from sibling tools, making the documentation complete.

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

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

Schema coverage is 100% (all params described). Description provides extensive guidance beyond schema: for topic param, explains what phrases work (distinctive arguments, statutory references) and what doesn't (bill names), and how to paginate with offset. The description adds significant practical value.

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

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

The description clearly states the tool's purpose: 'USE THIS TOOL WHEN you have a member_id and want contributions where THAT member used a specific topic phrase verbatim (text-body search).' It identifies verb, resource, and scope, and distinguishes from sibling tools like parliament_get_debate_contributions.

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 (text-body search for member's phrase), when not to use (verbatim retrieval of all contributions in a debate), and provides prerequisite (call parliament_find_member first). Also names an alternative tool for other use cases.

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

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint false. Description adds key behavioral details: hard-capped limit at 20 (verified live), pagination via offset, text truncation via max_description_chars, and authoritative status vs web search.

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

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

Description is front-loaded with usage guidance and well-structured. However, it is somewhat lengthy; could trim minor details like the exact date of verification without losing clarity. Still, every sentence adds value.

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

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

Given the tool's complexity (pagination, categories, content caps, authoritative source), the description covers all important aspects. It references response fields (totalResults, has_more) for pagination, and explains output schema implications without needing to replicate it.

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

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

Schema coverage is 100% with detailed descriptions for each parameter (limit, offset, category, member_id, max_description_chars). Description adds context like live verification of cap, pagination mechanics, and when to raise max_description_chars.

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

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

Description clearly states it retrieves registered financial interests for a UK MP or peer using a member_id. It lists categories (donations, directorships, etc.) and distinguishes from siblings like parliament_find_member by being the authoritative source for financial declarations.

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 member_id' and instructs to call parliament_find_member first. Provides pagination guidance for prolific members and notes to avoid web search for stale data.

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 details the tool's behavior: it aggregates Hansard debate-level signals with pure counts (no LLM), uses pagination up to max_debates_scanned, sweeps /search/Debates.json, and captures envelope counts. It also explains limitations regarding member-level facets. This adds significant context beyond the annotations (readOnlyHint, idempotentHint).

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

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

The description is well-structured with a clear opening directive, then explains the aggregation process, post-call instructions, limitations, and cross-references. Every sentence is informative and earns its place. Despite length, it is efficient and 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 tool's outputs (by_house, by_year, etc., and envelope counts), explains why certain facets are missing (member-level), and provides guidance on next steps. Considering the nested input schema and the fact that an output schema exists (mentioned in context), the description is comprehensive and leaves no critical gaps.

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

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

All parameters have descriptions in the input schema (100% coverage). The tool description for parameters adds extra context: e.g., for 'topic', it clarifies the semantics and differences from sibling tools; for 'max_debates_scanned', it explains defaults, maximum, and rate limits. This greatly enhances understanding beyond the schema.

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

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

The description starts with 'USE THIS TOOL WHEN' and clearly defines the tool's purpose: providing debate-level corpus signals (by_house, by_year, by_section breakdowns) without reading every contribution. It distinguishes from sibling tools by noting that member-level facets are not included and directing to other tools for those needs.

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

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

The description explicitly states when to use the tool and provides post-call guidance ('AFTER calling, pick a debate...'). It also explains what the tool does not do (member-level facets) and suggests alternative tools for such cases.

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

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint, openWorldHint. Description adds valuable context: pagination behavior (limit+offset), citation-grade metadata, authoritative source, and drill-down workflow. No contradiction with annotations.

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

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

Well-structured with clear sections and front-loaded purpose. Slightly lengthy due to rich explanations, but every sentence adds value. Could be more concise by removing some redundancy with schema descriptions.

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 and the presence of an output schema, the description covers all necessary aspects: workflow, pagination, alternatives, and parameter details. It is complete and self-contained for effective use.

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 description adds significant value beyond schema: explains that query searches speech text (not titles), gives examples of effective queries, clarifies preview vs full text modes, and details contribution_type and member_id nuances (e.g., deprecation of old field).

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

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

Description explicitly states 'USE THIS TOOL WHEN searching Hansard by topic, bill title, or text phrase', providing a specific verb and resource. It distinguishes from siblings like parliament_get_debate_contributions and parliament_find_member by outlining their distinct uses.

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 (topic/bill/text search) and when-not-to-use (do not text-search by member name). Offers clear alternatives: chain find_member then get_debate_contributions for member remarks, or policy_position_summary for breadth. Also warns against supplementing with web search.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds beyond this by stating what the response includes: 'title, state, signature count, and dates for government response or parliamentary debate if applicable', which is useful behavioral context.

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

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

The description is only 4 sentences, each purposeful. It is front-loaded with the action and resource, no redundancy, and uses clear imperative language.

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 4 parameters and an output schema, the description covers the essential aspects: what the tool does, what data it returns, and its authoritative source. It is complete enough for an agent to use correctly.

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

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

Schema coverage is 100% (all parameters have descriptions). The description reinforces the 'keyword or topic' for query and 'Filter by state' for state parameter, but adds minimal new meaning beyond the schema. Baseline of 3 is appropriate.

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

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

The description explicitly states 'USE THIS TOOL WHEN searching UK Parliament petitions by keyword or topic', clearly identifying the verb (search) and resource (petitions). It distinguishes from sibling tools like parliament_search_hansard and bills_search_bills by specifying petitions.

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

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

The description provides clear context: 'searching UK Parliament petitions by keyword or topic' and suggests filtering by state. It does not explicitly state when not to use or list alternatives, but the context is sufficient for an agent to decide.

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 non-destructive. The description adds valuable context: returns string content, with binary base64-encoded, no contradictions.

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

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

Three sentences, front-loaded with purpose, no unnecessary words, each sentence adds essential information.

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

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

Given the output schema exists (context signal), the description doesn't need to detail return format; it covers input, behavior, and encoding fully.

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

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

Schema coverage is 100% for the single 'uri' parameter, and the description adds meaning by explaining static vs templated URIs, which goes beyond the schema's 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 starts with a clear verb+resource statement ('Read a resource by its URI') and distinguishes between static and templated resources, which differentiates it from sibling tools like 'list_resources'.

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

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

It provides guidance on providing URIs for static vs templated resources, but lacks explicit when-not-to-use or alternatives, though the simplicity and sibling names make usage clear.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description adds important behavioral context: voter lists are truncated to 100 per side, but total voter counts are always accurate. This enhances transparency beyond what annotations provide.

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

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

The description is extremely concise: only 3 sentences, all essential. The first sentence is imperative and immediately states when to use the tool. No wasted words.

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

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

Given the tool's simplicity and the presence of an output schema, the description is complete. It explains the truncation limitation, usage scenario, and how to obtain the required parameter. No gaps remain.

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

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

Schema coverage is 100% with detailed descriptions. The description adds value by noting that division_id comes from votes_search_divisions results, which provides provenance context. This compensates for the lack of additional parameter details.

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 purpose: 'USE THIS TOOL WHEN you have a division_id + house and want the full member-by-member voting record.' It clearly identifies the verb (get), resource (division detail), and distinguishes from siblings by mentioning chaining from votes_search_divisions or parliament_get_debate_divisions.

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

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

The description provides clear when-to-use guidance (when you have division_id and house) and explicitly mentions alternative tools for obtaining the division_id: votes_search_divisions or parliament_get_debate_divisions. This helps the agent choose correctly.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds that it returns division summaries with title, date, vote counts, pass/fail, and notes the authoritative nature. This adds value but does not detail pagination or response structure beyond 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 three succinct sentences, all essential. It uses bold for key phrases and has no filler. Every sentence adds value.

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

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

Given the tool has 7 parameters and an output schema, the description is complete: it states the purpose, input scope, output summary, and next step. Schema covers parameter details. No gaps for an agent.

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

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

All parameters have descriptions in the input schema (100% coverage). The description does not add new parameter-level details but provides context about the output (division_id used in next step). 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 searches Commons or Lords formal votes by topic, date, or member. It distinguishes from sibling tools like votes_get_division by describing it as the initial search step.

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

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

Explicitly starts with 'USE THIS TOOL WHEN' and provides follow-up guidance to use votes_get_division with division_id+house. Mentions it is the authoritative source, giving clear context for use.

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