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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint false. The description adds behavioral details beyond annotations: the summary truncation behavior (capped per max_summary_chars with a truncation flag) and conditional inclusion of Royal Assent date. 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 with three sentences, each serving a distinct purpose: usage condition, return fields with caveat, and follow-up actions. No superfluous information.

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

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

Given the tool has only 2 parameters and an output schema, the description covers all necessary aspects: purpose, exact usage condition, parameter behavior, return fields, and recommended follow-up steps. It is complete for an agent to correctly invoke and interpret results.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value: for max_summary_chars, it explains the default, token equivalence, when to increase (for substantive bills), and the truncation check. For bill_id, it reiterates the source. This goes beyond the schema's own 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: to get full bill detail given a bill_id. It specifies the exact return fields (sponsors, stage, title, summary, assent date) and distinguishes itself from the sibling tool 'bills_search_bills' by noting that the bill_id comes from that search tool.

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

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

The description explicitly says 'USE THIS TOOL WHEN you have a bill_id (from bills_search_bills) and want the full detail.' It also provides post-call guidance on using parliament_search_hansard or bills_search_bills for related queries. While it doesn't explicitly state when not to use it, the prerequisite condition is clear.

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

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

Annotations already provide readOnlyHint, destructiveHint, idempotentHint, openWorldHint. Description adds that it returns a paginated page of bill summaries with fields (title, current stage, whether Act). Explains pagination pattern implicitly through offset/limit hints. 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?

Four sentences, front-loaded with usage instruction, no redundant information. Every sentence earns its place: use case, return format, next step, authority statement.

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 search capability, pagination, linking to sibling tool, and notes authoritative source. Output schema exists, so return values are covered. Complete for a search tool with 6 parameters.

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%, baseline 3. Description adds extra context for session (explains numeric ID vs year), offset (pagination re-call pattern), and limit (default and max). This goes beyond schema descriptions, providing actionable guidance.

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 explicit 'USE THIS TOOL WHEN searching UK parliamentary bills by keyword, session, house, or legislative stage', clearly stating the verb and resource. It differentiates from sibling 'bills_get_bill' by indicating this returns summaries, and after calling, pass bill_id to get full detail.

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

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

States exact use case upfront and instructs to use 'bills_get_bill' for full detail. Provides guidance on session parameter (numeric ID, not year) with fallback if only year known. No ambiguity.

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, destructiveHint=false, idempotentHint=true, and description adds return format (list of {eId, snippet, match}), regex fallback to literal substring, and cap on max_hits.

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

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

Description is front-loaded with 'USE THIS TOOL WHEN', followed by concise bullets. Every sentence adds value without redundancy.

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

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

Given the complexity (search within judgment with regex), the description covers input, output, and post-call procedure. Output schema exists, and description explains return value structure.

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 3. Description repeats fallback behavior for pattern and default for case_insensitive, but does not add significant new 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?

Title and description clearly state 'Search within a UK Court Judgment' with specific verb and resource. Distinguishes from sibling judgment_get_index which is for paragraph-number navigation.

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

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

Explicitly says 'USE THIS TOOL WHEN you have a judgment slug and want to find paragraphs whose text matches a pattern.' Also provides when-not-to-use alternatives like judgment_get_index for paragraph navigation.

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 behavior beyond annotations: returns paginated summaries, coverage period, and the fact that from_date/to_date filters are silently ignored by upstream. Annotations already mark it as read-only and idempotent, but the description adds critical operational details.

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

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

The description is long but well-organized with front-loaded purpose and structured paragraphs. Every sentence adds value, though some redundancy exists (e.g., 'pagination' repeated). Still efficient for the breadth of 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 8 parameters, output schema, and numerous sibling tools, the description is comprehensively complete: covers usage, parameter nuances, post-call workflow, coverage limitations, and caveats. Leaves no obvious 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?

Despite 100% schema coverage, the description significantly enhances parameter meaning: provides example for query, warns about judge honorifics causing zero results, explains page/limit slicing, and flags date filter bugs. Adds pragmatic guidance not in 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 a clear directive 'USE THIS TOOL WHEN searching UK case law', specifying the verb and resource. It lists the searchable fields (party names, court, judge, date, free-text) and differentiates from sibling tools by detailing post-search steps and 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?

Explicitly states when to use and provides exclusions (e.g., do not supplement with web search). It offers alternatives for specific tasks (case_law_grep_judgment for text within a single judgment, citations_resolve for verification) and strategic advice on narrowing results.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by stating it formats per OSCOLA 4th edition, is authoritative for UK legal citations, and makes no network call. It also describes refusal behavior for low confidence or missing resolved_url.

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 a single paragraph that is front-loaded with the main purpose and includes key instructions, but it could be slightly more structured. However, it is reasonably concise and 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 of the tool (14 parameters, multiple citation types), the description and schema together provide comprehensive guidance: usage, failure modes, and constraints. An output schema exists, and the description explains return behavior via status, 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?

With 100% schema coverage, each parameter is described as coming from citations_resolve, which is reinforced in the description. The description adds the crucial guidance that fields must not be guessed, providing 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?

The description clearly states the tool formats an OSCOLA citation string after citations_resolve, specifying the verb 'Format' and resource 'OSCOLA Citation String', and it implicitly distinguishes from siblings by being the only formatting tool.

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

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

The description explicitly says to use the tool after citations_resolve, instructs not to construct input fields but to pass from resolve, and details failure cases with guidance to surface errors, providing clear when-to-use and when-not-to-use.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, and the description adds context: it fetches judgment XML from TNA, parses OSCOLA citations, and returns results grouped, deduplicated, and sorted. This goes beyond annotations and provides full behavioral transparency.

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

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

The description is well-structured with a clear call-to-action at the start, followed by technical details and usage guidance. Every sentence adds value, and there is 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 that an output schema exists (context signal: 'Has output schema: true'), the description does not need to detail return values. It covers all necessary aspects: what, when, how, and follow-up steps. The tool is simple (one param) and the description is complete.

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

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

The single parameter 'case_uri' has a detailed description in the schema (100% coverage) that goes beyond basic type: it provides format examples, source advice ('use the 'uri' field from case_law_search results'), and what to exclude. This adds significant meaning.

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: mapping all citations (cases, legislation, SIs, retained EU law) from a judgment slug. It uses specific verbs like 'map' and 'fetch', and the title reinforces this. The description also distinguishes it from sibling tools 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 explicitly says when to use this tool ('when you have a judgment slug and want to map every citation it makes') and provides post-call guidance ('AFTER calling, pass any individual citation through citations_resolve'). This clarifies usage order and alternatives.

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

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

Annotations indicate readOnlyHint=true and destructiveHint=false, which the description matches. It adds behavioral context: default pure-regex parsing, optional LLM-based disambiguation via MCP sampling, and URL resolution without existence confirmation. This 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 well-organized with clear sections and bullet points. It is slightly verbose but every sentence adds value. The structure aids readability and comprehension.

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

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

Given the tool's complexity (multiple citation types, optional disambiguation, output schema exists), the description is complete. It covers usage, behavior, parameter details, and post-processing steps, leaving no major 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%, and the description adds meaningful detail beyond the schema. For 'text', it elaborates on supported citation formats; for 'disambiguate', it explains the trade-off and when to enable it. This provides practical guidance.

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 extracts and classifies OSCOLA-style citations from free text. It lists specific citation types and distinguishes from sibling tools like citations_resolve (verification) and citations_format_oscola (formatting).

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' and gives clear use cases. It also advises 'AFTER calling, pass each citation through citations_resolve to verify', providing a clear workflow and excluding misuse. It explains when to use the optional disambiguation parameter.

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 the live HTTP HEAD check for neutral citations, confidence=0.0 handling, ValueError on unrecognizable input, and the fabrication warning. These details go beyond annotations (readOnlyHint, idempotentHint) and provide 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 front-loaded with the key usage instruction and structured in paragraphs that each add value. It is longer than minimal but every sentence earns its place; minor tightening possible.

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

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

Given the tool's complexity (external resolution, error states, confidence handling) and presence of an output schema, the description covers all necessary behavioral aspects for correct agent usage, including failure handling and warnings against misuse.

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

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

The single parameter 'citation' has schema coverage 100%, but the description adds context on accepted formats (neutral citation, SI, legislation section) with examples, increasing semantic value beyond the schema description.

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

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

The description explicitly states the tool resolves OSCOLA citations to verify existence, and distinguishes from sibling 'citations_format_oscola' by warning against using the formatter without resolution. The verb 'resolve' and resource 'OSCOLA citation' are clear.

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

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

The description provides explicit when-to-use (before formatting or to confirm document existence) and when-not-to-use (do not manufacture citations on failure). It implies alternatives (the formatter) but does not explicitly name them as alternatives outside the warning.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false, so the description's addition of parallel fetching adds value beyond annotations 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 two sentences, front-loaded with usage condition, and every word is purposeful with no redundancy.

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

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

For a simple one-parameter tool with an output schema, the description covers the essential behavior and follow-up action, 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% and the parameter is well-described in the schema. The description does not add new semantics beyond what the schema already provides, so base score of 3 is appropriate.

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

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

The description clearly states the tool fetches committee detail and member list in parallel, using the verb 'Fetches' and specifying the resource as 'metadata + current membership'. It distinguishes from siblings by noting that evidence is handled by committees_search_evidence.

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

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

The description explicitly states 'USE THIS TOOL WHEN you have a committee_id and want the metadata + current membership' and advises to use committees_search_evidence for evidence, providing clear context and alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds that it returns committee summaries (name, house, active status, ID) and hints at further usage, but this adds minimal new behavioral context beyond the annotations.

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

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

The description is two focused sentences plus a follow-up line, all front-loaded with the core usage instruction. Every sentence adds value without redundancy.

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

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

Given the presence of an output schema, the description does not need to explain return values. It covers purpose, usage, and next steps sufficiently for a search/list tool with 4 optional parameters.

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

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

Schema description coverage is 100%, so the baseline is 3. The description briefly mentions filters (name, house, active status) but does not add meaningful detail beyond what is already in the schema descriptions.

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

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

The description explicitly states 'USE THIS TOOL WHEN searching or listing UK parliamentary select committees' with specific filters (name, house, active status). It clearly distinguishes from siblings by mentioning the next steps of passing committee_id to committees_get_committee or committees_search_evidence.

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

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

The description provides explicit guidance on when to use the tool and what to do after (pass committee_id to related tools). However, it does not explicitly state when NOT to use this tool or list alternative tools, though siblings are provided separately.

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, destructiveHint=false, idempotentHint=true, so the agent knows it is safe. The description adds valuable behavioral context beyond annotations: it explains pagination (returns one page, default 20, has_more), caps on free-text titles (max_title_chars) and witness lists (10 per item). 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 concise with three sentences, no fluff. It is front-loaded with 'USE THIS TOOL WHEN' for immediate usability. Every sentence adds value: usage condition, behavioral details, and authority statement.

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

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

Given the tool's complexity (pagination, multiple evidence types, caps), the description covers key aspects: what it returns, pagination loop, and caps. The output schema exists (not shown but indicated), so return structure is documented elsewhere. The 'Authoritative source' statement adds useful context. The description is complete enough for an agent to use correctly.

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

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

Schema description coverage is 100%, with each parameter already having a description. The tool description adds additional context, such as explaining offset usage for pagination and the effect of max_title_chars on title length. This complements the schema well, providing deeper meaning for parameters involved in pagination and output control.

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 committee_id and want the oral and written evidence submitted to it,' clearly specifying the verb (search/return) and resource (committee evidence). It distinguishes itself from sibling tools like committees_search_committees (lists committees) and committees_get_committee (details a single committee), so the purpose is specific and unambiguous.

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

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

The description explicitly states when to use the tool ('when you have a committee_id and want the oral and written evidence'). It also provides pagination guidance ('re-call with offset=offset+returned while has_more is true'). However, it does not explicitly state when not to use it or mention alternatives, though the sibling list and context signals partially cover that.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, indicating no destructive side effects. Description adds value by specifying return format ('JSON with a messages array') and argument structure, which annotations do not cover. No contradictions.

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

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

Three sentences, front-loaded with the main action, no unnecessary words. Every sentence adds distinct information: what it does, what it returns, and how to provide arguments.

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, description appropriately mentions the return format. It covers input parameters and basic behavior. Could mention error cases or prompt absence, but overall sufficient for a simple read-only tool with good annotations.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning by stating 'Arguments should be provided as a dict mapping argument names to values', which clarifies the structure of the optional object parameter beyond the schema's generic 'object' type.

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 verb 'Get', resource 'prompt', and method 'by name with optional arguments'. It distinguishes from sibling tool 'list_prompts' which lists prompts, as this tool retrieves a single specific prompt. Purpose is unambiguous.

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

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

Description implies usage for retrieving a specific prompt by name and notes optional arguments, but does not explicitly state when to use this tool over alternatives like 'list_prompts' nor mention conditions like prompt existence. Guidance is implicit rather than explicit.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds significant behavioral context: default sandbox connection, production override via HMRC_API_BASE, required OAuth credentials, and error behavior when credentials are missing. It also includes a caution not to infer status. 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 concise (roughly 80 words) and well-structured: a clear usage directive in the first sentence, followed by return details, environment setup, and credential requirements. Every sentence adds necessary information without redundancy.

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

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

For a simple tool with one parameter, annotations covering safety, and an output schema (context indicates it exists), the description covers all critical aspects: purpose, return content, environment configuration, credential prerequisites, and error conditions. There are no gaps given the tool's complexity.

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

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

The input schema provides a detailed description for the single parameter 'vrn' (format, examples, handling of GB prefix), giving 100% coverage. The tool description does not add additional parameter information beyond what the schema provides. Per the guidelines, high schema coverage warrants a 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 clearly states the tool's purpose: checking MTD VAT status for a given VAT registration number. It uses a specific verb ('check') and resource ('MTD status'), and the title reinforces this. Among sibling HMRC tools (e.g., hmrc_get_vat_rate, hmrc_search_guidance), this tool is uniquely identified, so no confusion.

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 9-digit VAT Registration Number and need that business's Making Tax Digital VAT mandate status.'). It also provides context about environment setup (sandbox vs production) and credentials. However, it does not explicitly state when not to use it or mention alternatives, but given the sibling tools cover different functionality, no exclusion is needed.

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 that the tool 'Uses a static lookup table current as of 22 Nov 2023 (Autumn Statement)' and notes that rates may have changed. This goes beyond annotations (readOnlyHint=true, idempotentHint=true) by explaining the data source and freshness. 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: three short sentences plus a bolded usage note. Every sentence provides essential information without redundancy. It is front-loaded with the usage directive.

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

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

Given the tool's simplicity (one parameter, read-only, output schema present), the description covers purpose, usage guidelines, data limitations, and fallback tool. It is complete and provides all necessary 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?

The parameter schema already provides a description ('Commodity code or plain-English description'). The tool description adds examples ('E.g. 'food', 'domestic fuel'', 'software'). This adds value beyond the schema, but does not specify format constraints or validation details, so it's above baseline but not perfect.

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 you have a UK commodity or service description and want its VAT rate category.' It clearly identifies the verb (get) and resource (VAT rate for commodity), and distinguishes from the sibling hmrc_search_guidance by noting it as a fallback 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?

The description gives explicit usage context: when you have a UK commodity/service and want its VAT rate. It also provides an important when-not-to-use guideline for time-sensitive advice, directing to hmrc_search_guidance. It mentions data currency limitations, helping the agent decide when to trust the result.

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 that it searches the official GOV.UK content API filtered to HMRC publications, and returns specific fields (titles, URLs, summaries, dates). This provides useful behavioral context beyond annotations, though rate limits or pagination are not mentioned.

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 (4 sentences) and front-loaded with the key instruction. Every sentence adds value: purpose, output, source, and authority.

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 simple search nature, complete annotations, and presence of an output schema, the description covers all necessary context: what it searches, what it returns, and its authoritativeness.

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 does not add new parameter semantics; it repeats the output format but not parameter details. The schema already explains 'query' and 'limit' adequately.

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

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

The description clearly states the tool's purpose: searching GOV.UK for HMRC tax guidance. It specifies the verb 'search', the resource 'GOV.UK HMRC tax guidance', and the scope (VAT, income tax, etc.). It implicitly distinguishes from siblings by noting that web search returns outdated info.

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 searching GOV.UK for HMRC tax guidance') and provides a negative guideline ('Web search returns out-of-date or third-party reproductions — do not supplement'), giving clear context and alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds value by specifying the return data types (parties, judges, neutral citation, etc.) and stating it is an 'Authoritative source for UK judgment metadata,' which complements the annotations 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 succinct with no redundant words. It front-loads the key action ('USE THIS TOOL WHEN') and provides necessary workflow context in a few clear sentences, earning its length.

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

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

With one well-described parameter, comprehensive annotations, and an output schema (not shown but indicated), the description covers all necessary context: when to use, prerequisite steps, and what the tool provides. No gaps remain for this simple tool.

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

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

Schema coverage is 100% with a clear description of the slug parameter including example formats. The description adds the context that the slug comes from case_law_search, but this is already implied by the parameter description. Baseline 3 is appropriate as the schema already does the heavy lifting.

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

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

The description explicitly states the tool retrieves metadata (parties, judges, citation, court, dates) given a judgment slug, distinguishing it from sibling tools like judgment_get_index and judgment_get_paragraph by placing it in a clear workflow (search first, then header, then index, then 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?

The description provides explicit when-to-use guidance: 'USE THIS TOOL WHEN you have a judgment slug and need metadata.' It also outlines the prerequisite step of calling case_law_search first and the subsequent steps of using judgment_get_index and judgment_get_paragraph, effectively guiding the agent on how to combine tools.

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

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

Annotations already indicate readOnly, non-destructive, idempotent. Description adds context about the returned data (eId + preview line) and the expected input origin, but doesn't add significant behavioral detail beyond that. 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?

Extremely concise: two sentences with clear, actionable instructions. No unnecessary words or repetition. Front-loaded with purpose and usage context.

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

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

Given the tool's simplicity (one parameter, output schema exists), the description adequately covers its purpose, input source, output content, and how to proceed afterward. Complements 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 covers the single 'slug' parameter with description and example. The description reinforces the parameter's role ('you have a judgment slug') but adds minimal semantic value beyond the schema, which already has 100% coverage.

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

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

The description clearly states the tool returns a paragraph navigation index (eId + preview line) given a judgment slug, and distinguishes from siblings like judgment_get_paragraph 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 instructs to call case_law_search first to obtain the slug, then use this tool, and afterwards use judgment_get_paragraph or case_law_grep_judgment. Provides clear workflow and alternatives.

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

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

Beyond annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), the description adds that the tool returns paragraph XML content with a typical token range (400–1,700 tokens). This provides useful behavioral context 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?

The description is extremely concise: two sentences that front-load the purpose and provide essential usage guidance without any unnecessary words. Every sentence serves a clear function.

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 required params, good schema coverage, annotations, output schema exists), the description covers all necessary context: purpose, prerequisites, output format, typical size, and sibling references. No gaps remain for this type of 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 input schema already describes both parameters well (slug format, eId normalization). The description adds context by linking eId to judgment_get_index and using the term 'LegalDocML eId', which reinforces the schema but does not significantly expand parameter meaning beyond what is already present. With 100% schema coverage, baseline is 3; the added context raises it to 4.

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

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

The description clearly states the tool's purpose: retrieving a paragraph's full text given a judgment slug and eId. It uses specific verbs ('get') and resources ('paragraph'), and distinguishes 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?

The description explicitly tells when to use the tool ('when you have a judgment slug + LegalDocML eId') and provides guidance on prerequisites ('Call judgment_get_index FIRST...or use case_law_grep_judgment'), which helps the agent decide between tools.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, openWorldHint. The description adds important context: content capped per max_chars, check content_truncated, always check extent for territorial applicability, and that schedules are not supported. No contradictions with annotations.

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

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

The description is two concise paragraphs. The first sentence immediately states when to use. Every sentence adds value: purpose, warning about extent, alternative, behavior of max_chars, and output hint. 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 5 parameters (4 required), full schema coverage, output schema exists, and detailed annotations, the description covers all necessary aspects: usage conditions, parameter behavior (especially max_chars and section format), important warnings (extent, truncation), and alternative tool. Complete for the task.

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%, but the description adds practical guidance beyond schemas, e.g., max_chars default ~2,500 tokens, raise for long definition sections, check content_truncated. For 'section', it clarifies to use numeric part only and that schedules not currently supported.

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 parsed text of a specific section with metadata. It distinguishes from the sibling tool read_resource by specifying this returns structured parsed data. The verb 'get' and resource 'legislation section' are clear.

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 you have a known Act / SI and want the parsed text...' and provides an explicit alternative: 'call read_resource(...) for raw CLML XML; use this tool when you want the parsed structured response instead.' It also advises to check extent, a recurring legal-research error.

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

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

Annotations already mark the tool as read-only, idempotent, and open-world. The description adds significant behavioral context: pagination via offset/limit, has_more and total_items, example of large statutes (Companies Act 2006), output format with XML ids and titles, and the workflow to pass numeric section ids to legislation_get_section. No contradictions with annotations.

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

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

The description is concise (about 150 words) and well-structured: usage instruction first, then output description, pagination details, and alternative tool. Every sentence adds value, with no repetition or fluff.

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

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

Given the presence of an output schema (not shown) and 100% schema coverage, the description is complete for core usage: input parameters, pagination, and cross-tool workflow. It could mention error conditions or prerequisites (e.g., valid type/year/number) but these are minimal 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 description coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining the purpose of offset/limit in pagination, providing default and max values, and clarifying that type codes come from search results. It also contextualizes parameters for large statutes.

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 the structural table of contents for a known Act or SI, using specific verb 'get' and resource 'table of contents'. It differentiates from siblings like legislation_get_section and read_resource by specifying distinct use cases and output formats.

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 when to use (known Act/SI, want TOC) and provides clear alternatives (read_resource for full TOC string, legislation_get_section for section text). It also explains pagination for large statutes. However, it does not explicitly state when NOT to use the tool, which would strengthen guidance.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description details exact-match filtering, zero-result risk, ranking, and next_steps hints. 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 purpose, each sentence adds value, and it is well-structured without redundancy. Despite detail, it remains concise and focused.

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 purpose, usage, filtering, chaining, and authority. Given the output schema exists, it need not explain return values. It is complete for a search tool of this complexity.

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

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

With 100% schema coverage, the description still adds significant value: examples for query, cautions for type/year, differentiation for fulltext, and explanation for limit. This extra context helps correct usage.

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

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

The description explicitly states the tool searches UK Acts and Statutory Instruments by title, phrase, or full-text, listing return fields and authoritative source. It distinguishes from sibling tools like case_law_search and bills_search_bills by specifying the scope of UK legislation.

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

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

The description opens with 'USE THIS TOOL WHEN' and provides clear guidance on when to filter by type/year (only when known) and when to use fulltext. It also chains to legislation_get_toc and legislation_get_section, and implicitly directs to other tools for bills or case law.

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, destructiveHint=false, idempotentHint=true, so the agent knows it's safe and idempotent. The description adds minimal behavioral context beyond the output format.

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 concise sentences that front-load the purpose. Every word contributes meaning 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 no parameters, rich annotations, and an existing output schema, the description fully covers what the agent needs to know: the action (list), the resource (prompts), and the return type (JSON metadata).

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

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

No parameters exist, and schema coverage is 100%. The description does not need to add parameter semantics, but it mentions 'optional arguments' in the output, which is relevant to the return 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 'List all available prompts.' and specifies the return format (JSON with metadata), making the purpose unambiguous and distinct from siblings like get_prompt and list_resources.

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

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

The description implies usage (to list prompts), but does not explicitly guide when to use or provide alternatives. Siblings like get_prompt suggest a pattern, but no direct guidance is given.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds value by detailing the return format (JSON with metadata) and distinguishing static vs template resources, which is 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?

Two concise sentences with front-loaded purpose, no unnecessary words.

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

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

Given no parameters, an output schema exists, and the description covers the tool's listing behavior, it is complete for its simple function.

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?

Zero parameters, baseline 4. No parameter documentation needed.

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 specifies 'List all available resources and resource templates' with clear differentiation between static and template resources, providing distinct fields and template placeholders. This is specific and not a tautology.

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?

Clear context that this tool lists all resources and templates, implicitly for discovery. No explicit when-not or alternatives mentioned, but the purpose is straightforward.

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, destructiveHint, idempotentHint, and openWorldHint. The description adds behavioral context: the tool returns multiple matches for common names (disambiguation) and must be called before other member_id-based tools. This enriches the agent's understanding 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 efficiently structured: first line states use case and output, second paragraph details return fields, third provides workflow guidance. No redundant sentences; each sentence adds critical information.

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

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

Given the tool's simplicity (one parameter, clear purpose), the description covers all necessary aspects: input semantics, output structure, disambiguation, and integration with sibling tools. The presence of an output schema further reduces the description's burden, but it still provides a useful summary.

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

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

With 100% schema description coverage, the description adds value by explaining how the 'name' parameter is used (query to find members) and what the result contains. It also gives examples ('Starmer', 'Baroness Hale') and notes that partial names work, which is helpful beyond the schema's minimal description.

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

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

The description clearly states the tool's purpose: given a member's name, return their integer member_id. It specifies the output fields (id, party, constituency, house, status) and distinguishes itself from sibling tools by positioning itself as a prerequisite for member_id-based filtering tools.

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

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

The description explicitly tells when to use this tool ('when you have a member's name and need their integer member_id') and when not to skip it ('CALL THIS BEFORE any tool that filters by member_id'). It lists specific sibling tools that depend on it and warns against alternative approaches (text-searching by name) using an example (Pannick case).

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

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

Annotations already provide readOnlyHint, destructiveHint, idempotentHint, openWorldHint. Description adds context about expected item count (100-200), clarifies that vocabulary doesn't matter, and warns against reconstructing quotes. Does not contradict annotations.

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

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

Compact yet thorough. Every sentence adds value—usage instruction, chain guidance, behavioral notes, and a pitfall warning. Well-organized with clear sections.

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 complexity, annotations, and output schema, the description covers all necessary aspects: when to use, how to chain, what to expect, and how to handle empty results. Complements structured fields effectively.

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

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

Schema coverage is 100%, so baseline is 3. Description reinforces schema information (e.g., where to get debate_ext_id, effect of member_id) but does not add significant new parameter semantics beyond what schema already provides.

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

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

Clearly states verb (get contributions), resource (debate contributions), and scope (by debate_ext_id, optionally filtered by member_id). Distinguishes from sibling tools like parliament_member_debates by explaining the difference in filtering logic.

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 (when you have debate_ext_id) and when to provide member_id vs omit. Provides a typical chain with other tools and instructs to report empty results honestly, avoiding hallucination.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds cross-resolution details, that votes_id may be None, and that empty list is not an error. No contradictions, but could mention rate limits or other behaviors.

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 and bullet points. Slightly verbose but each sentence adds value. Could be tightened but 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 output schema exists (not shown), description provides necessary workflow context (two IDs, cross-resolution, post-processing). Does not explain full output fields, but schema handles that.

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

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

Schema coverage is 100% with a single parameter. Description explains where to get the debate_ext_id (from other tools), adding value beyond the schema's basic description.

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

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

The description clearly states the tool fetches divisions (formal votes) for a given debate_ext_id. It distinguishes from siblings like votes_get_division and votes_search_divisions by explaining the returned IDs and 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 states 'USE THIS TOOL WHEN you have a debate_ext_id and want the divisions.' Provides context on when divisions typically occur (bill stages, motions) and notes that empty list is honest. Also instructs to pass votes_id to votes_get_division for full records.

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 readOnly and idempotent hints; the description adds valuable behavioral details: explanation of contribution_count, source codes with interpretations, behavior on empty matches (surface failure, not assume fabrication), and that resolution is not gated on publication state.

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

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

Well-structured with example, after-call instructions, output field interpretation, and common errors. Slightly verbose but each section serves a purpose.

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

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

Given the tool's complexity and the presence of an output schema, the description is thorough: covers usage, output meaning, failure modes, and follow-up steps. No gaps evident.

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

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

Input schema covers all 3 parameters with descriptions (100% coverage). The description adds extra meaning: clarifies that volume_number is required and date is not a substitute, and explains column_number suffix usage. This adds value beyond the schema.

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

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

The description clearly states the tool resolves an OSCOLA-style Hansard column citation to find the debate, with a concrete example. It distinguishes from sibling tools like parliament_search_hansard and parliament_get_debate_contributions by specifying that this tool is for column 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 says 'USE THIS TOOL WHEN you have an OSCOLA-style Hansard citation...' and provides post-resolution steps. While it doesn't explicitly state when not to use it, the context is clear and the example aids selection.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false. Description adds that text is capped at 3000 characters, explains the text-body search nature, and clarifies filtering behavior. 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 clear sections, but could be slightly more concise. Still, every sentence adds value and front-loads purpose.

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

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

Covers purpose, parameters, usage guidelines, behavioral quirks (text cap), pagination, and references sibling tools. Adequate for a tool with 4 params and output 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 coverage is 100%, but description adds valuable context for 'topic' parameter (e.g., what phrases to search, avoid bill names) and explains offset pagination. Significantly enhances schema.

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

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

The description starts with 'USE THIS TOOL WHEN...' and clearly states the verb (get contributions), resource (member contributions by topic phrase), and differentiates from sibling tool 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?

Provides explicit when to use (having member_id and wanting contributions with specific phrase) and when not to use (for all contributions regardless of vocabulary, use parliament_get_debate_contributions). Also gives prerequisite to call parliament_find_member first.

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. Description adds critical details: hard cap on limit (verified live), pagination logic, and max_description_chars. Could mention rate limits but not required given 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?

Well-structured, front-loaded with use case and prerequisite. Each sentence adds distinct value without redundancy. Appropriate length for the tool's complexity.

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

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

Given 5 parameters, presence of output schema, and sibling tools, the description fully covers pagination, filtering, limits, and source authority. No gaps remain for agent decision-making.

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 5 parameters fully (100% coverage). Description adds value by explaining limit cap, pagination mechanism, and purpose of max_description_chars, going beyond schema basics.

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

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

The description clearly states 'get their registered financial interests' with specific categories. It distinguishes from siblings by noting it's the authoritative source and referencing the prerequisite parliament_find_member.

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

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

Explicitly says 'USE THIS TOOL WHEN you have a member_id and need their registered financial interests.' Provides prerequisite call to parliament_find_member and pagination instructions.

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, destructiveHint=false, idempotentHint=true. The description adds significant behavioral context: 'Pure counts — no LLM, no editorial labels' and explains the aggregation process (sweeps /search/Debates.json with pagination, aggregates by house/section/year/month/top_debates). It also mentions rate limits (1000 req/5min) and envelope counts from /search.json. 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 appropriately sized and front-loaded with the usage guideline. Every sentence provides necessary information: what the tool does, how it works, what to do after, limitations, and parameter details. No wasted words; it is comprehensive yet 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 tool's complexity (5 parameters, 1 required, output schema exists), the description covers all aspects: purpose, inputs, process, outputs (by_house, by_year, etc.), limitations (no member-level facets), and post-call actions. It is fully complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% (all 5 parameters described). The description adds value beyond the schema: for 'topic', it explains that bill titles work due to debate-level matching; for 'max_debates_scanned', it explains the default corresponds to ≤4 upstream calls and can be raised for exhaustive sweeps with rate limit context. This compensates fully for the rich 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: aggregating debate-level corpus signals on a topic (by_house, by_year, by_section) without reading every contribution. It uses a specific verb-resource pair ('aggregate Hansard debate-level signals') and distinguishes from siblings like parliament_search_hansard 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?

The description explicitly starts with 'USE THIS TOOL WHEN' and provides usage context. It instructs users to pick a debate from top_debates and call parliament_get_debate_contributions for detail. It also explains when not to use (for member-level facets) and suggests alternative tools (parliament_member_debates, hansard://debate).

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, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds rich behavioral context: it details return fields (member_id, column_ref, debate_id, etc.), pagination behavior (limit+offset, has_more), tokenised matching behavior, the fact that bill titles often fail due to speech patterns, and the distinction between preview and full text modes. 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 structured with clear sections (USE THIS TOOL WHEN..., Returns..., DO NOT..., Pagination..., Authoritative source...). It is front-loaded with the core purpose. However, it is somewhat verbose with redundant explanations (e.g., the resource path for full contribution text appears twice). Each sentence earns its place, but minor conciseness improvements are possible.

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

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

Given the tool's complexity (9 parameters, output schema exists, many sibling tools), the description is remarkably complete. It covers search behavior, pagination, integration with other tools, warnings about query semantics, and authoritative claims. It leaves no obvious gaps for an AI agent to make mistakes.

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 value beyond schema by explaining parameter behavior in context (e.g., tokenised matching for query, that bill titles don't match well, the distinction between contribution_type affecting pagination scope, and the resource path for full text in text_mode). It also clarifies that member_id requires an integer ID from parliament_find_member.

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: 'USE THIS TOOL WHEN searching Hansard by topic, bill title, or text phrase.' It clearly identifies the verb (search), resource (Hansard), and scope (by topic, bill title, text phrase). It also distinguishes from siblings like parliament_find_member, parliament_get_debate_contributions, and parliament_policy_position_summary.

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

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

The description provides explicit when-to-use and when-not-to-use guidance. It states 'DO NOT text-search by member name' and directs to a chained workflow (parliament_find_member → parliament_get_debate_contributions). It also notes alternatives for broader topic searches (parliament_policy_position_summary) and emphasizes that this is authoritative, advising against supplementing with web search or training-data recall.

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, destructiveHint=false, idempotentHint=true, covering safety. The description adds what data is returned (title, state, etc.), but does not discuss rate limits, authentication, or pagination beyond schema. The description incorrectly lists 'debated' as a state option, which is not in the schema, causing slight confusion.

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

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

Three sentences with no fluff. The first sentence immediately states the tool's purpose, and the rest are succinct. 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?

The output schema exists and covers return data, but the description introduces an error by suggesting 'debated' is a valid state, which contradicts the schema (only open, closed, all). This misleading information reduces completeness. The tool's pagination is partially covered in the offset schema description, but the description itself omits important behavioral details like default limit and offset recommendations.

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 briefly mentions filtering by state, but does not add new meaning beyond the schema descriptions for query, offset, or limit. No additional guidance on parameter values is provided.

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's for searching UK Parliament petitions by keyword or topic, and specifies it returns title, state, signature count, and dates. It distinguishes itself from sibling tools by declaring it the authoritative source for petitions.

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

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

The description opens with 'USE THIS TOOL WHEN' which explicitly sets usage context. It suggests filtering by state and mentions narrowing to live or historical petitions. However, it does not explicitly forbid use cases or direct to alternatives, but given it's the only petition tool, that's acceptable.

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, non-destructive, idempotent, and open-world behavior. The description adds value by detailing return format (string, base64 for binary), which the annotations do not cover.

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

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

Four clear sentences, each earning its place. The most critical information (reads by URI) appears first, followed by usage details and return format. 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 (one parameter, rich annotations, output schema exists), the description covers input formatting and return type. It could mention error cases (e.g., resource not found) but is otherwise complete.

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

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

The description adds significant meaning beyond the schema: it explains how to construct the URI for both static and templated resources, which the schema's brief description does not convey.

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 reads a resource by its URI, distinguishing between static and templated resources. This is a specific verb+resource pair that differentiates from sibling tools like 'list_resources' or specialized readers.

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

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

The description provides explicit guidance on URI format for static vs. templated resources, aiding correct parameter usage. However, it does not explicitly state when to use this tool over sibling tools or when not to use it.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description adds critical behavioral detail: 'Voter lists are truncated to 100 per side to fit response limits; total voter counts are always accurate regardless of truncation.' This informs the agent of important limitations and guarantees.

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

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

Three sentences, each purposeful. The first sentence front-loads the usage condition, the second explains a key behavioral trait, and the third gives chaining options. No wasted words.

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

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

The description covers when to use, key behavioral details (truncation), and sourcing guidance. With an output schema present and full parameter descriptions, no further information is needed for correct invocation.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds no additional meaning 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 'USE THIS TOOL WHEN you have a division_id + house and want the full member-by-member voting record.' This is a specific verb-resource pairing and distinguishes from sibling tools like votes_search_divisions by specifying the context of having the ID.

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

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

The description provides explicit when-to-use guidance with the imperative directive. It also indicates where to obtain the division_id (from votes_search_divisions or parliament_get_debate_divisions), effectively telling the agent when not to use this tool (when they don't have an ID).

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. Description adds 'Authoritative source' but does not disclose pagination behavior or any additional behavioral nuances 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?

Four sentences, first sentence front-loaded with usage instruction. No wasted words, 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 full schema coverage, annotations, and an implied output schema, the description completes the picture by indicating the workflow (use with votes_get_division) and stating the source authority.

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 7 parameters. The description adds a brief note on using after for full lists but no additional parameter-level meaning beyond what is in the schema.

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

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

Clearly states the verb 'search' and resource 'Commons or Lords formal votes' with specific facets (topic, date, member). Distinct from sibling votes_get_division by noting that this tool returns summaries and the other provides detailed voter lists.

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' and provides when-not-to-use by directing to votes_get_division for full lists, giving a clear workflow.

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