UK Legal Research

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 beyond annotations: it lists returned fields (sponsors, current stage, etc.), notes the summary character cap and truncation indicator, and explains adjustability of max_summary_chars. No contradiction with annotations.

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

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

The description is well-structured with a clear 'USE THIS TOOL WHEN' lead, followed by a list of return fields, a note on parameter behavior, and post-call suggestions. Every sentence adds value; 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 presence of an output schema (as noted in context signals), the description does not need to detail return values. It covers the tool's purpose, usage context, parameter specifics, and follow-up actions. It is 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%, yet the description adds significant meaning: bill_id's origin is clarified, and max_summary_chars includes detailed guidance on default value (5000), adjustment for large bills, and how to check truncation. This provides context beyond the schema's properties.

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 directive 'USE THIS TOOL WHEN you have a bill_id... and want the full detail.' It specifies the verb (get), resource (bill detail), and distinguishes from sibling tools by noting the source of the bill_id. The tool is properly named and scoped.

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 bill_id from bills_search_bills and want the full detail') and provides post-call recommendations: use parliament_search_hansard for debates or bills_search_bills for adjacent bills. This gives clear guidance on alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds that it returns paginated bill summaries with fields like title, current stage, and whether it became an Act, plus it claims authority. No contradictions.

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

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

The description is concise and well-structured. The first sentence front-loads the purpose. No unnecessary words; every sentence adds value. Ideal length for an agent to quickly grasp.

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 return format (paginated summaries), hints at the workflow (use bills_get_bill for details), and provides filter dimensions. With an output schema assumed present, this is fully adequate.

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

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

Schema coverage is 100% with detailed parameter descriptions. The tool description adds valuable usage tips: the session parameter nuance (numeric ID, not year string) and pagination via offset. This extra context aids correct invocation.

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 parliamentary bills by keyword, session, house, or legislative stage.' It clearly identifies the resource (bills) and action (search), and distinguishes from sibling tools like bills_get_bill.

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: when to search bills and suggests following up with bills_get_bill for full detail. It does not explicitly state exclusions, but the workflow guidance 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?

Discloses that pattern is regex with fallback to literal substring, return format (list of {eId, snippet, match}), and that results are small snippets. Annotations already indicate read-only, idempotent, non-destructive; description adds valuable behavioral details.

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

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

Front-loaded with 'USE THIS TOOL WHEN', brief yet comprehensive. Every sentence is purposeful, 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?

Covers return format, workflow (use with judgment_get_paragraph), search behavior, and parameter details. Output schema exists, but description independently explains enough.

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

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

Schema covers all parameters with descriptions (100% coverage). The description adds context about regex fallback for pattern and clarifies the purpose of eId in combination with other tools, but does not significantly expand on parameter meaning 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 'USE THIS TOOL WHEN you have a judgment slug and want to find paragraphs whose text matches a pattern.' It distinguishes from siblings like judgment_get_index and judgment_get_paragraph.

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

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

Explicitly tells when to use, provides alternatives, and gives examples like 'negligence', 'test for foreseeability'. It also explains the workflow of reading full paragraphs after searching.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds behavioral details: paginated summaries, date filter caveat (silently ignored), judge filter case-insensitivity, and coverage limitations. 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?

Front-loaded with purpose, then structured with returns, post-call steps, strategy, coverage, and authority. Every sentence adds value; no redundancy. Efficiently guides agent without excess.

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

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

Given 8 parameters, output schema, and complex sibling ecosystem, the description is complete. Covers usage, post-call workflow, caveats, and authoritative source. No gaps identified.

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

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

Schema coverage is 100% with good descriptions. The tool description enhances semantics by providing strategic usage context for parameters (e.g., narrowing with court+year, judge filter quirks, limit slicing). 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 it searches UK case law and distinguishes from siblings like case_law_grep_judgment and citations_resolve. It specifies search dimensions (party names, court, judge, date, free-text) and emphasizes authoritative source.

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

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

Explicitly says 'USE THIS TOOL WHEN searching UK case law' and provides detailed post-call guidance, narrowing strategies, and warnings against supplementing with web search. It also advises on filtering before iterating.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds details about refusal conditions (confidence=0.0, missing resolved_url), the fact that it's authoritative with no network call, and its role as a guard against citation fabrication.

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 (about 120 words) and well-structured: usage instruction, behavior explanation, warnings. 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 complexity (14 parameters, 5 citation types) and the presence of an output schema, the description covers all essential aspects: when to use, how it behaves, refusal conditions, and guardrails. No gaps.

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

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

Schema coverage is 100% (baseline 3). The description adds meaning by emphasizing that inputs must come from citations_resolve, explains the special handling of 'raw' for EU retained law, and clarifies the refusal logic for confidence and resolved_url. This exceeds the schema alone.

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 formats OSCOLA citation strings after using citations_resolve, distinguishing it from siblings like citations_resolve and citations_parse. The purpose is clear and specific.

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 use instructions: 'USE THIS TOOL AFTER citations_resolve', warns against constructing input manually, and specifies what to do when it refuses. Alternatives and context for when-not-to-use are provided.

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

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

Description details behavior beyond annotations: fetches judgment XML from TNA, parses OSCOLA citations, returns grouped by type, deduplicated, and sorted. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false, and description adds context without contradiction.

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

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

Description is seven sentences, all providing essential information. Front-loaded with purpose, no redundancy or filler.

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

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

Given the single parameter, clear schema, and annotations, the description fully covers usage context, workflow (fetch, parse, group, sort), and the next step (citations_resolve). Output schema exists, so return values need not be detailed.

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 case_uri, whose schema description already provides comprehensive guidance (slug format, source field, prefix exclusion). The tool description doesn't add significant meaning beyond what the schema offers, so baseline 3 is appropriate.

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

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

The description clearly states the tool maps every citation in a judgment, including cases, legislation, SIs, and retained EU law. It specifies the verb 'map' and resource 'citations network', and distinguishes from siblings like citations_resolve.

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

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

The description begins with 'USE THIS TOOL WHEN you have a judgment slug', clearly indicating when to use it. It also instructs to pass citations to citations_resolve after calling, providing a clear workflow. No explicit when-not conditions, but the context implies this is the first step.

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

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

Annotations already indicate readOnlyHint=true. The description adds that parsing is pure regex by default, and optional disambiguation uses MCP sampling (model in loop). It also states that citations resolve to TNA URLs when possible. This provides behavioral context beyond annotations.

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

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

The description is well-structured with a clear 'USE THIS TOOL WHEN' opening, a list of citation types, an explanation of disambiguation, and a post-call advice. It is slightly verbose but every sentence is informative and earns its place.

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

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

Given the presence of an output schema, the description adequately covers the tool's scope, limitations (regex by default, optional disambiguation), and workflow integration with 'citations_resolve'. It references sibling tools and provides actionable guidance.

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

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

Schema coverage is 100%, but the description adds value by explaining the purpose of each parameter: 'text' is free text with supported citation types, and 'disambiguate' is a boolean for optional model-based resolution. This goes beyond the schema's minimal 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-style citations from free text. It lists specific citation types (neutral citations, law reports, etc.) and distinguishes itself from the sibling 'citations_resolve' by advising to use that for verification after parsing.

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

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

The description explicitly says 'USE THIS TOOL WHEN you have free text...' and provides a follow-up action ('pass each citation through citations_resolve'). It also explains when to opt into disambiguation. However, it does not explicitly mention when not to use the tool or compare with other siblings like 'citations_network'.

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

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

Describes live TNA HEAD check, confidence-0.0 behavior, transient error handling with ToolError and retryable flag. Adds context beyond annotations (readOnlyHint, idempotentHint). 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?

Well-structured with imperative first line, then details and warnings. Every sentence adds value, though slightly verbose. Front-loaded with key usage instruction.

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

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

Complete for a tool with live checking and error handling. Covers success, failure, retry, ethical warnings. Output schema exists, so return values not needed in description.

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

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

Only one parameter with 100% schema coverage. The example in description adds context but does not significantly expand beyond schema's description. 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 specifies the verb 'parses + resolves' and the resource 'a single citation', listing exact types (neutral citation, SI, legislation section, retained EU law). It distinguishes from siblings like citations_format_oscola (formatting) and citations_parse (parsing without resolution).

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

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

Explicitly states when to use: 'BEFORE constructing an OSCOLA citation string' or 'to confirm a citation points at a real document'. Provides exclusions: 'Do NOT format or quote a confidence-0.0 citation'. Mentions alternatives: retry or proceed without TNA verification on transient errors. Warns against fabrication.

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 safe read-only, open-world, idempotent behavior. The description adds behavioral detail about parallel fetching and the composite output (detail + member list), which is not captured by 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 focused sentences plus a third for next steps. No filler, every sentence earns its place. Usage instruction is front-loaded as requested.

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, extensive annotations, and an output schema, the description covers purpose, usage, behavioral traits, and parameter origin completely.

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 committee_id as integer. Description adds crucial context: committee_id comes from 'committees_search_committees results', linking tools and preventing misuse.

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 'metadata + current membership' for a committee given its ID, using verbs 'Fetches committee detail and member list'. It distinguishes itself from sibling 'committees_search_evidence' by suggesting a follow-up action.

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

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

The description explicitly says 'USE THIS TOOL WHEN you have a committee_id', provides a clear use case, and tells the agent what to do after calling, implicitly excluding the sibling tool for evidence 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 provide readOnlyHint, idempotentHint, etc. The description adds return fields and parameter nuances (e.g., limit covers active committees, query filtered client-side), adding value without contradiction.

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

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

The description is very concise: one sentence for purpose, one for returns, one for next steps. Front-loaded with imperative, 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 moderate complexity and existing output schema, the description covers essential information: what it does, what it returns, and how to chain to related 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?

Schema coverage is 100%, so baseline is 3. The description adds context beyond the schema, like explaining default limit coverage and client-side filtering, enhancing understanding.

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

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

The description starts with a clear imperative: 'USE THIS TOOL WHEN searching or listing UK parliamentary select committees by name, house, or active status.' It identifies the specific resource and verbs, and distinguishes from siblings by mentioning follow-up tools.

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

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

Explicitly states when to use ('USE THIS TOOL WHEN...') and provides guidance on next steps, but does not explicitly contrast with other search tools among siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description's job is to add context. It does so by disclosing the one-page behavior, caps on titles and witness lists, and the authoritative source. 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 extremely concise, using three sentences to convey all necessary information. It front-loads the use-case with 'USE THIS TOOL WHEN' and then efficiently covers pagination, caps, and authority. Every sentence is purposeful.

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 (indicated by context signals), the description doesn't need to explain return values. It covers pagination mechanics, caps, and the authoritative nature. For a search tool with clear parameters, this provides complete context for an agent to use it correctly.

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

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

Schema coverage is 100%, providing descriptions for all 5 parameters. The description adds value by explaining the rationale behind the max_title_chars cap (prevents context blow-up) and confirming the pagination pattern. This goes beyond the schema, justifying a 4.

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

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

The description clearly states that the tool searches for oral and written evidence by committee_id. It distinguishes from sibling tools like committees_search_committees and committees_get_committee by specifying the evidence focus. The verb 'search' and resource 'evidence' are 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?

The description explicitly instructs to use the tool when you have a committee_id. It provides detailed pagination guidance, including how to handle multiple pages with offset and has_more. This is actionable and makes the tool's usage clear without confusion.

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 context beyond annotations by specifying the return format (JSON with messages array) and the argument format (dict). It aligns with annotations and provides useful behavioral details.

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

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

The description is concise, with three sentences that front-load the core purpose, then explain return type and arguments. No extraneous information.

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

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

For a read-only tool with annotations and output schema, the description adequately covers purpose, return type, and argument structure. Missing error handling or edge cases, but acceptable.

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 coverage, the description adds only minor clarification about argument format. It does not significantly enhance 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 clearly states the tool retrieves a prompt by name with optional arguments, distinguishing it from listing tools. However, the term 'prompt' is not defined, leaving some ambiguity about what exactly is being retrieved.

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

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

The description explains what the tool does but does not provide explicit guidance on when to use it versus alternatives like list_prompts, nor 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?

The description adds behavioral context beyond annotations: it connects to HMRC sandbox by default, requires environment variables, and raises error if unconfigured. Annotations already indicate readOnly, idempotent, and non-destructive, and description aligns perfectly.

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 composed of four concise sentences, each providing unique value: purpose/usage, return fields, environment setup, and error handling. It is front-loaded and 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 single parameter, detailed annotations, and existence of an output schema, the description covers purpose, usage, return values, and operational notes. It is complete for a straightforward check tool.

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

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

The single parameter 'vrn' has 100% schema coverage with detailed description (format, length, GB prefix handling). The description only mentions it as '9-digit VAT Registration Number' without adding 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 verb 'Check' and the resource 'MTD VAT Status', specifying it checks Making Tax Digital mandate status for a business given a VRN. It is distinct from sibling tools like hmrc_get_vat_rate.

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

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

The description starts with 'USE THIS TOOL WHEN' and provides clear conditions (having a 9-digit VAT Registration Number). It also mentions sandbox vs production and credential requirements. However, it does not explicitly state when not to use or list 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: it uses a static lookup table current as of 22 Nov 2023, and notes that rates may have changed, advising verification for time-sensitive cases. 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 concise and well-structured: a bold usage instruction, a clear list of return fields, and an important caveat about data freshness. Every sentence adds value with no redundancy.

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

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

Given the tool's simplicity (single parameter, output schema present, comprehensive annotations), the description is complete. It covers purpose, usage, return values, data source limitations, and provides an alternative for time-sensitive queries.

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

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

Input schema has one parameter 'commodity_code' with a detailed description and examples, achieving 100% schema description coverage. The tool description does not add additional meaning beyond what the schema already provides for this parameter, so baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: to get the VAT rate for a UK commodity or service description. It distinguishes itself from sibling tools like hmrc_search_guidance by specifying its scope and directing users to alternative tools for time-sensitive advice.

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

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

Explicit usage guidance: 'USE THIS TOOL WHEN you have a UK commodity or service description and want its VAT rate category.' It also clarifies when not to use it (for time-sensitive advice, use hmrc_search_guidance 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?

The description adds value beyond the annotations by specifying the source (GOV.UK content API filtered to HMRC publications), noting the authoritative nature, and warning about out-of-date third-party information. Annotations already indicate readOnly, idempotent, non-destructive, but the description provides essential 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 extremely concise—four sentences with no fluff. The first sentence is directive and front-loaded with the core purpose. Every sentence adds value (usage guidance, return format, source, warnings).

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

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

Given the tool's simplicity (2 parameters, no nested objects, output schema exists), the description covers all necessary context: what it searches, what it returns, its authoritative nature, and limitations. No gaps for the agent to infer.

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 clear parameter descriptions. The description compensates by providing example queries (e.g., 'VAT digital services') and explaining that `limit` is passed to GOV.UK search count param, adding context beyond the schema while maintaining conciseness.

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 specific verb ('searching') and resource ('GOV.UK for HMRC tax guidance'), lists example tax types (VAT, income tax), and distinguishes it from sibling search tools by specifying the domain (HMRC guidance) and source (GOV.UK API).

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

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

The description explicitly says 'USE THIS TOOL WHEN searching GOV.UK for HMRC tax guidance', providing clear context. It also warns against using web search for this purpose, implying when not to use it (third-party sources). However, it does not explicitly name alternative tools for other search needs.

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 provide readOnly, idempotent, and non-destructive hints. Description adds details about content truncation (max_chars default and adjustment) and response fields to check (content_truncated).

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

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

Description is concise (9 sentences), front-loaded with purpose, and every sentence adds value without repetition.

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

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

Given output schema exists, description need not detail return format; it covers usage, behavioral notes, and parameter specifics adequately. Warning about extent completes the context.

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

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

Schema coverage is 100%, but description adds concrete usage details: for section parameter, 'Use the numeric part only' and schedules not supported; for max_chars, specific guidance about Finance Act sections 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 clearly states the tool retrieves parsed text of a legislation section with extent and in-force metadata, and differentiates from siblings like legislation_search and read_resource.

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

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

Explicitly states when to use (known Act/SI, want parsed structured response), provides alternative (read_resource for raw XML), and includes a strong warning about checking extent.

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 annotations: it indicates the output contains structural elements with XML id and title, explains pagination behavior with has_more/total_items, and instructs to pass numeric section identifiers to legislation_get_section. 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 usage guidance, then explains output and pagination, followed by an alternative. It is structured and each sentence adds value, though slightly verbose but still concise enough.

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

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

Given the tool has an output schema, the description appropriately covers usage context, pagination, and alternatives without needing to detail return values. It provides complete guidance for an agent to use the tool 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?

Input schema has 100% description coverage. The description adds usage context for limit and offset (e.g., 'Raise only when you need a larger slice', 'Use with limit to page through very large statutes') and clarifies that type comes from search results, enhancing 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 you have a known Act / SI and want the structural table of contents', providing a specific verb and resource. It distinguishes from sibling tools like legislation_get_section and read_resource by stating alternatives.

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 and provides an alternative (read_resource URI) for a different representation. It also explains pagination usage with offset/limit for large statutes, but lacks explicit 'when not to use' exclusions.

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

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

Both annotations and description are present. Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds: authoritative source (legislation.gov.uk), ranked results with next_steps hints, exact-match behavior for filters, and explanation of title vs full-text search. 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?

Well-structured with bold directive at start, clear separation of output, workflow, and filter discipline. Each sentence adds value, but slightly verbose; could be tightened slightly without losing 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 presence of an output schema (not shown), the description adequately covers return format (title, type, year, etc.) and next steps. No gaps for a search tool with good annotations and schema.

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%. Description adds value beyond schema comments by explaining exact-match behavior for type and year, giving workflow advice (omit if unsure), examples for query, and differentiation between title and full-text search for fulltext parameter. Limit parameter explanation is relevant.

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

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

Starts with 'USE THIS TOOL WHEN searching UK Acts and Statutory Instruments', clearly specifying the verb (search) and resource. Distinguishes from sibling tools like bills_search_bills and case_law_search.

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

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

Explicitly tells when to use this tool, provides chain workflow (legislation_get_toc then legislation_get_section), and gives detailed filter discipline: use type and year only when known, otherwise omit. Recommends querying by phrase for currency-driven searches and setting fulltext=True for broader concept queries.

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

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

Annotations already indicate read-only and idempotent behavior. Description adds return format details (JSON with metadata), but no additional behavioral traits beyond what annotations provide.

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

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

Two sentences: first states purpose, second states output. No wasted words, efficiently 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?

With an output schema present, the description appropriately explains the return structure. No critical gaps for a simple list tool.

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

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

No parameters in schema (0 params), so baseline of 4 applies. Description does not need to add param info as none exist.

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 'List all available prompts' with a specific verb and resource. While it distinguishes from the sibling tool `get_prompt`, it does not explicitly contrast them.

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

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

No guidance on when to use this tool versus alternatives like `get_prompt`. The context lacks when-not or context for usage.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds value by detailing the return format (JSON with resource metadata) and explaining the difference between static resources and templates, which goes beyond annotations.

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

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

The description is three short sentences, each essential. It front-loads the main purpose and adds structural details about resource types without 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 the tool's simplicity (no parameters), the description provides sufficient context about the purpose and output format, especially with an output schema presumably covering return fields. The explanation of static vs template resources ensures completeness.

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

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

The tool has no parameters, so schema coverage is 100%. The description does not need to add parameter info; the baseline is 4 for zero parameters. No further clarification required.

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

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

The description clearly states the tool lists all available resources and resource templates, distinguishing between static resources and templates with specific field details ('uri' vs 'uri_template'). This differentiates it from siblings like 'list_prompts' and 'read_resource'.

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

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

The description implies usage for exploring available resources but does not explicitly state when to use this tool versus alternatives like 'read_resource'. No exclusion or when-not guidance is provided, relying on sibling 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 indicate readOnly, idempotent, and non-destructive behavior. The description adds that it returns all matches, disambiguates common names, and returns specific fields (id, party, constituency, etc.). 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?

Concise, well-structured description with a clear action directive, bullet-like return info, and workflow context. 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?

Completely covers the tool's role in the workflow, return fields, disambiguation, and usage consequences. Given the output schema exists, the description provides sufficient context for an AI agent to use it correctly.

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

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

Schema coverage is 100%, and the description provides examples ('Starmer', 'Baroness Hale') and constraints (maxLength, minLength) beyond the schema, adding 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: convert a member's name to an integer member_id. It specifies the return fields and disambiguation of common names, making it very distinct from sibling tools.

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

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

Explicitly instructs to use this tool before any ID-based filtering tools, listing specific tools and warning against skipping this step with a concrete example (Pannick case). Provides clear workflow guidance.

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

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

The description discloses key behaviors: it returns verbatim contributions, when member_id is omitted it returns all contributions (~100-200 items), and it warns against reconstructing quotes from training data if the wire returns empty. The annotations already declare readOnlyHint, idempotentHint, and non-destructive; the description adds useful behavioral context without contradicting them.

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

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

The description is three paragraphs plus a closing instruction. It is front-loaded with the primary usage directive. While it is somewhat lengthy, every sentence adds value—paraphrasing schema details, providing chains, and warning against hallucination. Minor redundancy could be trimmed, but overall well-structured.

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

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

Given that an output schema exists, the description appropriately omits return value details. It covers usage context, parameter relationships, behavior with and without member_id, and troubleshooting (empty results). The tool's complexity is low (2 params, no enums, simple return), and the description is fully self-contained within that scope.

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

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

The input schema has 100% coverage with descriptions for both parameters. The description enhances these by explaining the practical significance of member_id (filtering by MemberId vs text) and debate_ext_id (chain from other tools). It adds meaning beyond the schema's mechanical 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 title 'Get Contributions In A Debate' and opening sentence clearly specify that the tool retrieves verbatim contributions given a debate_ext_id, optionally filtered by member. It distinguishes itself from sibling tools like parliament_member_debates and parliament_search_hansard by explaining the difference in filtering logic (by MemberId vs text).

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 ('USE THIS TOOL WHEN you have a debate_ext_id'), explains the typical chain of tools (find_member → search/debate_ext_id → this tool), and contrasts with text-search tools that filter by vocabulary. It also advises on handling cases with no contributions, providing clear contextual 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 indicate readOnly, idempotent, and non-destructive behavior. The description adds context about empty lists not being failures, explains the two ID spaces (Hansard and Votes API) and the cross-resolve mechanism with an extra HTTP call, which goes beyond annotation hints.

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

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

The description is well-structured with clear sections (usage statement, notes on emptiness, two IDs, cross-resolve). Each sentence adds value without redundancy, and it is concise given the complexity.

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

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

The description explains the two returned IDs and their purposes, handles edge cases (empty list), and mentions the extra HTTP call. It is complete for a tool that has an output schema, and no explanation of return values is missing.

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

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

Only one parameter (debate_ext_id) with 100% schema description coverage. The description adds extra context beyond the schema by explaining where to chain the ID from (parliament_search_hansard, etc.), raising it above the baseline of 3.

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

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

The description starts with 'USE THIS TOOL WHEN you have a debate_ext_id and want the divisions (formal votes) held within it.' It clearly specifies the verb 'get divisions' and the resource 'debate', distinguishing it from siblings like votes_get_division 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...'), notes that most debates contain no divisions and that an empty list is honest, and provides downstream instructions ('AFTER calling, pass votes_id as division_id into votes_get_division').

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

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

Discloses key behaviors: resolution is not gated on publication state, interpretation of source codes, and common failure reasons. All align with annotations (readOnly, idempotent). No contradictions.

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

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

Well-structured with example, bullet points, and clear sections. Slightly long but justified by the complexity; could trim minor redundancies.

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

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

Fully explains output fields (contribution_count, source_code), failure modes, and post-resolution steps. Output schema exists but description provides practical context. Completeness is high.

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 critical context: column_number as string to allow suffixes, volume_number as required and date not a substitute, house enum default behavior. 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 resolves OSCOLA-style Hansard citations with a specific input example. It distinguishes from sibling tools like parliament_search_hansard by focusing on column resolution rather than search.

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

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

Explicitly states 'USE THIS TOOL WHEN' followed by the citation format. Provides guidance on when to use complementary tools (read_resource, parliament_get_debate_contributions) and what empty matches mean, including instructions to surface failures.

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 the tool as read-only, idempotent, non-destructive. The description adds important behavioral details: the text-body search is verbatim, contributions are filtered by the exact topic phrase, and each contribution's text is capped at 3000 characters. This goes beyond annotations but does not mention rate limits or authentication requirements.

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, with clear sections for usage, prerequisites, behavior, and alternatives. Every sentence adds value, and the critical information is presented upfront.

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

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

Given the availability of a detailed input schema, annotations, and an output schema, the description covers all necessary context: when to use, prerequisites, behavior, limitations, and alternatives. It is complete and leaves no ambiguity 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?

All four parameters have detailed descriptions in the schema (100% coverage). The tool description adds extra context for the topic parameter (e.g., examples of what to search) and reiterates the prerequisite for member_id. This adds value beyond the schema alone.

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

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

The description clearly states the tool's purpose: retrieving contributions where a specific member used a particular topic phrase verbatim. It distinguishes itself from the sibling tool parliament_get_debate_contributions by specifying that this tool performs a text-body search, not a retrieval of all contributions in a debate.

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

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

The description explicitly tells when to use this tool (when you have a member_id and want verbatim text-body search) and what prerequisite action to take (call parliament_find_member first). It also provides a clear alternative (parliament_get_debate_contributions) for retrieving all contributions regardless of phrasing.

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, openWorldHint), the description discloses pagination behavior, a hard cap of 20 per call, a default limit, and a max_description_chars cap. Also notes data authoritativeness and freshness differences vs web search. This adds significant value.

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

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

The description is well-structured with clear sections and front-loaded purpose. Slightly verbose due to all-caps emphasis and extra details, but each sentence contributes necessary guidance. Could be slightly tightened without losing clarity.

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

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

Given 5 parameters, pagination complexity, and an existing output schema, the description covers prerequisite, usage, pagination, data source authoritativeness, and parameter behaviors. It is sufficiently complete for an AI agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, but the description adds substantial meaning: explains member_id's origin, limit's hard cap, offset for pagination, common category enums, and when to raise max_description_chars. This goes well beyond the schema's minimal 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 retrieves registered financial interests for UK MPs and peers, with specific examples (donations, directorships, land, gifts). It distinguishes itself from sibling tools like parliament_find_member and parliament_get_debate_contributions by focusing on financial interests.

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

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

Explicitly instructs to use when a member_id is needed for financial interests and provides a prerequisite: call parliament_find_member first. Includes pagination instructions. Does not explicitly mention alternatives, but the context and 'USE THIS TOOL WHEN' provide clear direction.

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. The description adds significant behavioral context: 'Pure counts — no LLM, no editorial labels', 'Sweeps /search/Debates.json with pagination', 'Hansard rate limit: 1000 req/5min', and details about max_debates_scanned. 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 clear sections (USE THIS TOOL WHEN, aggregation description, after-calling guidance, limitations note). It front-loads the purpose in bold. While somewhat lengthy, every sentence adds value. Minor redundancy could be trimmed but overall effective.

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 (mentioned in context signals), the description does not need to detail return values. It adequately covers the tool's purpose, usage, limitations, and relationship to sibling tools. It provides complete guidance for an AI agent to correctly select and invoke the tool.

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

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

Schema description coverage is 100%. The description adds meaningful context for parameters, especially 'topic' which explains matching semantics and why Bill titles work, and 'max_debates_scanned' which explains default behavior and rate limit implications. This goes beyond the schema's 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: 'Aggregates Hansard debate-level signals on a topic... Pure counts — no LLM, no editorial labels.' It distinguishes from sibling tools by specifying that it provides corpus-level breakdowns without reading every contribution, and contrasts with parliament_get_debate_contributions for drilling into specific debates.

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: 'USE THIS TOOL WHEN you want debate-level corpus signals on a topic — by_house, by_year, by_section breakdowns — without reading every contribution.' It also provides clear follow-up guidance: 'AFTER calling, pick a debate from top_debates and pass its debate_ext_id into parliament_get_debate_contributions.' Additionally, it explains what the tool does not provide (member-level facets) and directs to alternative tools for that information.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds significant behavioral context: pagination via limit+offset, query tokenization behavior, bill title matching caveat, text_mode details, and response metadata (total_corpus, has_more). 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?

Front-loaded with purpose, structured in clear paragraphs, no unnecessary words. Every sentence provides value. Concise given the complexity.

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

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

Complete for a search tool with output schema: covers workflow (drill into full content via read_resource or parliament_get_debate_contributions), pagination, parameter intricacies, and sourcing. No gaps.

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

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

Schema coverage is 100%, but the description adds crucial meaning: explains query tokenization, bill title mismatches, member_id clarification (old member field issue), text_mode behavior, and offset pagination details. Significantly enriches 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: 'USE THIS TOOL WHEN searching Hansard by topic, bill title, or text phrase.' It specifies the verb (search) and resource (Hansard), and distinguishes it from siblings like parliament_find_member and 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?

Explicit guidance on when to use (by topic/bill/text) and when not (member name), plus alternatives: chain parliament_find_member → parliament_get_debate_contributions for member search, or parliament_policy_position_summary for breadth. Also notes authoritative source.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context: it returns specific fields (title, state, signature count, dates) and notes that results include government response or debate dates if applicable. No contradictions with annotations.

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

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

Three short paragraphs, each earning its place. The usage directive is front-loaded. No redundant or unnecessary sentences. Highly 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 output schema (mentioned) and annotations, the description covers all needed aspects: purpose, parameters, return fields, filtering, pagination hints (offset description explains re-call logic), and authoritative source. No gaps.

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

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

Schema coverage is 100%, so the schema fully documents all parameters. The description adds minimal additional meaning (e.g., example search terms for query), but baseline 3 is appropriate since it doesn't introduce new semantic information 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 starts with 'USE THIS TOOL WHEN searching UK Parliament petitions by keyword or topic,' clearly specifying the exact resource (UK Parliament petitions) and action (search). It distinguishes from sibling tools like bills_search_bills by focusing exclusively on 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?

Explicitly states when to use the tool (searching petitions) and mentions filtering by state to narrow results. While it doesn't explicitly list when not to use it, the sibling context and clear scope make usage unambiguous.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral details: returns content as string, with base64 encoding for binary data. This goes beyond the annotations.

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

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

The description is three concise sentences, front-loaded with the core purpose, and every sentence adds distinct 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 a single simple parameter and an output schema that presumably details return structure, the description is complete: it covers the two resource types and mentions encoding for binary content. No gaps remain for an agent to understand usage.

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

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

The schema description for the 'uri' parameter is minimal ('The URI of the resource to read'), but the tool description adds crucial context: for static resources provide exact URI, for templated resources fill in parameters. This meaningfully enhances the schema information.

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

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

The description clearly states 'Read a resource by its URI' and elaborates on static vs templated resources, making the purpose unmistakable. It implicitly distinguishes from sibling tools that are specific to resource types (e.g., bills_get_bill).

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

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

The description explains when to use based on having a URI and handling static vs templated resources, but does not provide guidance on when to use alternative sibling tools that are more specific, such as legislation_get_section or judgment_get_paragraph.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds important behavioral context: voter lists are truncated to 100 per side for response limits, but total counts remain accurate. This goes beyond annotations and provides practical knowledge for agent usage.

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

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

The description is concise with two sentences: a clear usage directive and a behavioral note. Every sentence adds value, and the structure is front-loaded for immediate understanding. No unnecessary information is present.

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

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

The description covers the core purpose, prerequisites, and a critical behavioral detail (truncation). With an output schema existing, return formatting is not needed. Some context about potential errors or edge cases is missing, but overall it is sufficiently complete for the tool's simplicity.

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

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

Input schema coverage is 100%, so both parameters (division_id and house) are fully described in the schema. The description only mentions the parameters without adding new semantic details. Per guidelines, baseline 3 is appropriate as the schema already carries the burden.

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

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

The description explicitly states the tool's purpose: retrieving the full member-by-member voting record given a division_id and house. It distinguishes itself from sibling tools by directing chaining from votes_search_divisions or parliament_get_debate_divisions, making the purpose clear and specific.

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 instructions: 'USE THIS TOOL WHEN you have a division_id + house'. It also suggests chaining from specific tools to obtain the needed division_id. However, it does not explicitly state when not to use the tool or offer alternative tools for similar tasks, slightly reducing clarity.

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, covering safety. The description adds that it returns division summaries (title, date, vote counts, pass/fail) and states it's the authoritative source. No behavioral 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?

Description is 4 sentences, front-loaded with the usage instruction, no filler. Each sentence adds value: purpose, return type, workflow hint, and authority claim.

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 7 optional parameters, full schema coverage, and availability of output schema, the description effectively communicates the tool's role and how it fits into a search-and-detail workflow. It mentions return fields and source authority, making it complete.

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

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

Schema description coverage is 100%, with detailed descriptions for all 7 parameters. The tool description does not add parameter-level semantics beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description explicitly states the tool's purpose: searching Commons or Lords formal votes by topic, date, or member. It uses a clear verb (search) and resource (parliamentary divisions), and distinguishes from sibling tool votes_get_division by outlining the workflow.

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

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

The description starts with 'USE THIS TOOL WHEN' specifying the exact scenario. It also provides clear guidance on the follow-up tool (votes_get_division) for full details, effectively differentiating use cases.

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