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

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

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

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

The description is compact, roughly four sentences, with a clear 'USE THIS TOOL WHEN' lead and no redundant filler. Each segment (condition, returns, follow-up) earns its place.

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

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

With a comprehensive output schema, read-only annotations, and full parameter documentation, the description covers the essential context: when to call, what it returns, truncation behavior, and suggested subsequent actions. It's complete for the tool's complexity.

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

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

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

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

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

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

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

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

The description opens with an explicit conditional: 'USE THIS TOOL WHEN you have a bill_id (from bills_search_bills) and want the full detail.' It also provides a clear follow-up action (parliament_search_hansard) and alternative search suggestion, though it doesn't explicitly name competing tools to exclude.

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

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

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

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

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

The description is concise and well-structured: it leads with the usage trigger, then the return summary, then the follow-up workflow, and ends with a credibility statement. Every sentence serves a purpose with no fluff, and the most important usage guidance is front-loaded.

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

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

The description covers the essential usage context: when to use, what it returns, and how to follow up. It mentions pagination and the fields returned, which aligns with the output schema. The guidance to use bills_get_bill for detail completes the workflow. For a search tool with a rich schema and output schema, this is comprehensive.

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

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

Schema coverage is 100%, so all parameters are already well-documented in the input schema. The description mentions search dimensions (keyword, session, house, stage) which map to parameters, but it does not add further semantic depth beyond what the schema provides. It appropriately relies on the schema's detailed parameter descriptions.

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

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

The description explicitly states the tool's function: searching UK parliamentary bills by keyword, session, house, or legislative stage. It clearly distinguishes itself from the sibling bills_get_bill, which provides full detail, by noting it returns summaries. The purpose is unambiguous and differentiated.

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

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

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

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety. The description adds valuable behavioral context: it returns only small snippets (not full paragraphs), and it discloses the regex fallback to literal substring search if compilation fails. This goes beyond the annotations and is helpful for setting expectations.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Discloses important quirks beyond the annotations: from_date and to_date are silently ignored by the upstream endpoint, judge honorifics zero the result set, and coverage only starts from the early 2000s. These details complement the read-only/idempotent hints and give the agent realistic expectations.

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

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

The description is dense but well-structured: a direct usage directive, a clear post-call workflow, and focused caveats. Every sentence contributes practical guidance, and the length is justified by the tool's complexity and the number of quirks it must convey.

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

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

Covers return value shape (neutral citation, court, dates, slug, TNA URI), integration with sibling tools, coverage limitations, and a note on authoritative sources. This gives the agent a complete operational picture beyond what the schema and annotations provide.

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?

Even though schema coverage is 100%, the description adds essential parameter behavior: the date filters are unreliable, the judge parameter needs a bare surname to avoid silent zero results, and limit slices client-side. This meaningfully extends the schema definitions.

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

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

The description opens with a clear directive: 'USE THIS TOOL WHEN searching UK case law by party names, court, judge, date, or free-text query.' This names the specific resource and lists the search criteria, clearly distinguishing it from sibling tools that retrieve judgment components or resolve citations.

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 guidance and names alternatives: pass slug into judgment_get_header / judgment_get_index / judgment_get_paragraph for content, use case_law_grep_judgment for text within a single judgment, and citations_resolve to verify citations. It also advises against using web search as a supplement, giving a clear exclusion.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses refusal behavior: 'Refuses (status: upstream_validation) if confidence is 0.0... or if a neutral citation has no resolved_url.' It also states 'no network call' and warns against manufacturing citations. This adds significant behavioral context that annotations alone do not provide.

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

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

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

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

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

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

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

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

Schema description coverage is 100%, so the schema fully explains each parameter. The description adds an overarching rule that all parameters must come from citations_resolve, but this is more of a usage guideline than parameter semantics. The schema already covers details like confidence refusal and the EU-retained-law raw handling, so the description adds no new per-parameter meaning. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'produce the correctly formatted OSCOLA citation string.' It also distinguishes from siblings by explicitly saying 'USE THIS TOOL AFTER citations_resolve,' placing it clearly in the pipeline relative to citations_parse and citations_resolve.

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

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

The description provides explicit when-to-use guidance: 'USE THIS TOOL AFTER citations_resolve' and 'Pass the parsed fields returned by citations_resolve directly into this tool.' It also gives strong exclusions and failure-handling instructions: 'DO NOT construct the input fields yourself,' 'surface the failure and ask the user for the source URL or better identifying details.' This is comprehensive and actionable.

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

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

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

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

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

The description is front-loaded with the usage condition and is organized into three focused paragraphs. All sentences contribute useful context, though the format is slightly more verbose than necessary for the information conveyed.

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

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

The description covers the input precondition (judgment slug), what the tool does (parse TNA XML for OSCOLA citations), output characteristics (grouped, deduplicated, sorted), and follow-up action (use citations_resolve). With an output schema present, it is fully complete for this tool's complexity.

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

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

The schema description for case_uri is thorough (slug format, use 'uri' field, no prefix), providing 100% coverage. The description only reiterates the concept of a 'judgment slug' without adding new parameter-level semantics, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool maps all citations a judgment makes, including cases, legislation, SIs, and retained EU law. It distinguishes itself from sibling tools by emphasizing the network-wide mapping and integration with citations_resolve.

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

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

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

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

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

Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description adds critical behavioral context: parsing is pure regex by default, optional disambiguation invokes the client's own LLM via MCP sampling, and recognition of citation shape does not guarantee document existence. This meaningfully informs the agent of limitations and side effects (model-in-the-loop) that annotations cannot convey.

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

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

The description is well-structured with clear sections: a bolded usage trigger, a list of supported citation types, parsing behavior, and a follow-up instruction. It is front-loaded with the most important 'when to use' information and every sentence contributes operational value without redundancies.

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

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

Given the tool has only 2 parameters, an output schema, and rich sibling context, the description fully covers the essential operational details: input type, output scope, disambiguation behavior, URL resolution, and the requirement to verify via citations_resolve. It clearly differentiates itself from the resolve and format siblings, so an agent can select and invoke it correctly.

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

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

Schema coverage is 100%, and the parameter descriptions already fully explain the text and disambiguate parameters. The tool description repeats the supported citation types and the disambiguation behavior, adding little new semantic value beyond the schema. It does hint at URL resolution as output, but that is not a parameter-level detail.

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

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

The description opens with a specific action ('extract and classify every OSCOLA-style citation') and identifies the target resource (free text). It lists concrete citation types and explicitly separates itself from sibling tools like citations_resolve by stating what it does not do (confirm existence). The verb and scope are precise and unambiguous.

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

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

The description clearly states when to use the tool ('USE THIS TOOL WHEN you have free text... and want every OSCOLA-style citation... extracted and classified') and explicitly directs the agent to follow up with citations_resolve for verification. It does not explicitly say when not to use it, but the alternative/next-step guidance is strong and actionable.

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

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

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

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

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

The description is well-structured and front-loads the usage directive, but some safety warnings are repeated (e.g., not formatting or quoting unresolved citations). The redundancy is understandable for risk mitigation but prevents a perfect conciseness score.

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

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

The description covers input, output shape, error behavior, retry semantics, and downstream safety considerations. Given the presence of an output schema, the additional context about confidence and resolved_url is sufficient for an agent to use the tool correctly.

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

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

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

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

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

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

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

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

The description explicitly instructs agents to use this tool before constructing an OSCOLA citation string or confirming that a citation points to a real document. It also provides critical guidance about not manufacturing citations when resolution fails, which clearly defines when and how to use the tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, lowering the burden. The description adds valuable behavioral context by noting that committee detail and member list are fetched in parallel, and it reveals the intended follow-up workflow. This goes beyond simple safety disclosure, though it doesn't detail response structure or pagination (which are covered by the output schema).

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

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

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

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

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

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

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

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

Schema description coverage is 100% and the single parameter committee_id is already well-described in the schema as coming from committees_search_committees results. The description does not add additional semantic meaning beyond that, so the baseline of 3 is appropriate.

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

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

The description clearly states this tool fetches committee detail and member list, with an explicit 'USE THIS TOOL WHEN...' condition. It distinguishes itself from sibling search tools by requiring a committee_id and focusing on metadata + membership.

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

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

The description provides explicit when-to-use guidance ('when you have a committee_id and want metadata + current membership') and adds a workflow pointer to committees_search_evidence. However, it does not explicitly state when not to use it or name alternative tools for lookup scenarios, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds useful context about the return values ('committee summaries (name, house, active status, ID)') and the recommended next steps, but it does not disclose any non-obvious behaviors (e.g., client-side filtering, pagination details) that are not already in the schema. Given the annotations, the description adds moderate value beyond structured data.

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

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

The description is short and efficient, with only two sentences. It front-loads the primary purpose in the first sentence and packs follow-up guidance into the second, avoiding any fluff or redundant repetition of schema details.

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

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

With a robust input schema (100% coverage), output schema, and comprehensive annotations (readOnlyHint, idempotentHint, destructiveHint), the description only needs to clarify the tool's role and workflow. It does so effectively, including the critical downstream step of passing committee_id to other tools, making it complete for the given complexity.

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

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

Schema coverage is 100%, meaning every parameter (house, limit, query, active_only) has a description in the input schema. The tool description does not add any additional parameter-specific semantics beyond what the schema already provides, so it meets the baseline of 3 without elevating.

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

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

The description states a specific verb ('searching or listing') and resource ('UK parliamentary select committees'), with clear filtering dimensions ('by name, house, or active status'). It also distinguishes itself by referencing downstream tools (committees_get_committee, committees_search_evidence), clearly separating its role from siblings.

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

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

The opening instruction 'USE THIS TOOL WHEN' explicitly marks the intended use case. It also provides clear context by describing the follow-up workflow ('AFTER calling, pass committee_id into...'), but it does not explicitly name alternatives when this tool should NOT be used, though sibling tool differentiation is implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint, so safety profile is covered. The description adds substantial behavioral context: pagination behavior (one page, has_more), ordering for evidence_type='both', caps on free-text titles and witness lists, rendering of organisation vs null witnesses, and the 'Authoritative source' note. This goes well beyond annotations and no contradiction exists.

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

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

The description is front-loaded with the usage condition and then provides dense operational details. While it is relatively long, every sentence adds value (pagination, caps, rendering rules). The structure is logical—first when to use, then behavior. It could be trimmed slightly, but it is appropriately sized 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?

The tool has 5 parameters, pagination, ordering, caps, and witness rendering rules, and the description covers all these aspects. It mentions the return includes 'total' and explains pagination. Since an output schema exists, it need not fully describe return values. The description is complete enough for an agent to call the tool correctly without ambiguity, including hints for efficient pagination.

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

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

Schema coverage is 100%, so each parameter is documented in the schema. The description adds meaning beyond the schema: it explains what 'both' means for evidence_type (oral first, then written), the purpose of max_title_chars (prevents context blow-up), and how offset works in the combined sequence. This enriches the raw schema definitions, so a score above the baseline of 3 is warranted.

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

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

The description opens with 'USE THIS TOOL WHEN you have a committee_id and want the oral and written evidence submitted to it,' which states a specific verb (search/get), a specific resource (committee evidence), and a clear condition. It clearly distinguishes this tool from sibling tools like committees_get_committee (which retrieves committee details) and committees_search_committees (which searches committees) by focusing on evidence. The title 'Search Committee Evidence' reinforces the purpose.

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

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

The description gives an explicit condition for use ('when you have a committee_id and want evidence') and details on pagination ('re-call with offset=offset+returned while has_more is true'). It implies alternatives by naming the exact scenario, but it does not explicitly state 'do not use for committee search' or mention sibling tools. The guidance on when to use is strong, but exclusion criteria are only implied, not stated.

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

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

The annotations indicate readOnlyHint, idempotentHint, and non-destructive behavior, which match the description's 'get' action. The description does not mention side effects, but the annotations cover this. No contradictions.

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

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

The description is concise, using two short sentences to convey the purpose and parameter format. No fluff or redundancy.

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

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

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

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

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

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

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

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

The description clearly states that the tool retrieves a prompt by name with optional arguments, distinguishing it from sibling tools like list_prompts which list available prompts. The verb 'get' and resource 'prompt' are explicit.

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

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

The description implies usage when a specific prompt is needed, and the sibling list_prompts provides the alternative for listing. Though not explicit, the context is sufficient for an agent to decide when to use this tool.

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

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

Annotations already mark the tool as readOnly and idempotent, and the description adds valuable behavioral context: default sandbox connection, production override via HMRC_API_BASE, required OAuth credentials, and that it raises if credentials are missing. This goes beyond the structured fields without contradicting them.

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

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

The description is concise and front-loaded with the core purpose, followed by return details and environment notes. Every sentence provides value, though the environment configuration section could be trimmed without losing clarity.

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

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

Given the tool's simplicity, the description covers the main use case, return fields, environment defaults, and error behavior. The presence of an output schema further reduces the need to explain return format, making this complete.

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

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

The schema fully describes the only parameter (vrn) with format and example, and the description does not add new parameter information. With schema coverage at 100%, the baseline of 3 is appropriate.

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

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

The description states a specific action and resource: 'USE THIS TOOL WHEN you have a 9-digit VAT Registration Number and need that business's Making Tax Digital VAT mandate status.' It clearly explains the return value (mandated status, effective date, trading name) and distinguishes from other HMRC tools like hmrc_get_vat_rate.

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

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

The description provides an explicit trigger: 'USE THIS TOOL WHEN you have a 9-digit VAT Registration Number and need that business's Making Tax Digital VAT mandate status.' It also gives environment setup and warns against inferring status without credentials, though it does not name alternative tools for when-not-to-use.

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

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

The annotations already mark the tool read-only, idempotent, and non-destructive; the description adds important behavioral details such as exact-match normalization, the rule that extra qualifying words are not discarded, the null response for unresolved queries, and the fact that notes list category names. This goes well beyond the structured annotations.

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

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

The description is front-loaded with the triggering condition and is generally dense and efficient. A few details about return fields overlap with what an output schema would likely provide, but every section contributes actionable guidance.

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

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

For a single-parameter, read-only, idempotent lookup tool, the description covers when to use it, exact matching semantics, success and failure output shapes, and a retry/alternative path. Nothing essential is missing for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, but the description materially enhances the single parameter by clarifying it must exactly equal a category name, not free text, and by giving normalization rules and explicit examples. It also explains what happens when the parameter does not resolve to a category.

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

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

The description states the exact purpose: a named-category VAT lookup, and explicitly contrasts it with a free-text classifier. It is specific about the resource and behavior, and the sibling tools like hmrc_search_guidance are clearly distinct.

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

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

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

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by disclosing that it queries the official GOV.UK content API filtered to HMRC publications and that it returns titles, URLs, summaries, and last-updated dates. This goes beyond the safety annotations to clarify the data source and return payload.

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

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

The description is concise and front-loaded with the key when-to-use directive. Every sentence serves a purpose: the search scope, the return fields, the data source, and the authoritative nature. No filler or redundancy.

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

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

Given the output schema is present and annotations declare the safety profile, the description is complete for an agent to select and invoke the tool correctly. It covers the source, scope, return contents, and even warns against using web search as an alternative.

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

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

Schema description coverage is 100%, with both 'query' and 'limit' having descriptive definitions and example values. The description itself adds minimal parameter semantics, but the schema fully covers parameter meaning, so the baseline of 3 is appropriate.

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

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

The description explicitly states the tool searches GOV.UK for HMRC tax guidance on specific topics like VAT and income tax. It clearly identifies the resource (HMRC guidance) and the action (search), separating it from sibling search tools for legislation or parliament.

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

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

It begins with 'USE THIS TOOL WHEN searching GOV.UK for HMRC tax guidance' and explicitly warns against web search, stating it returns out-of-date or third-party reproductions. This provides clear when-to-use and when-not-to-use guidance, and implicitly distinguishes it from other search tools.

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

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

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

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

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

Three sentences, front-loaded with 'USE THIS TOOL WHEN', each sentence earns its place: usage trigger, workflow, authority. No redundancy or fluff.

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

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

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

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

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

Schema coverage is 100% with a clear description and examples for the 'slug' parameter. The description adds the context of needing a slug from case_law_search but doesn't provide new parameter-level semantics beyond the schema. Baseline 3 is appropriate.

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

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

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

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

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

Explicitly states when to use: 'when you have a judgment slug and need metadata'. Provides workflow: call case_law_search first, then use judgment_get_index/paragraph. Naming alternatives and prerequisite tools makes usage context unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so safety is covered. The description adds that the tool returns an eId and preview line for every paragraph, which is useful behavioral context beyond the annotations. It does not mention error handling or pagination, but the output schema likely covers return structure.

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

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

The description is concise and front-loaded with the usage trigger. Every sentence provides necessary information: what it does, when to use it, and how it fits with other tools. No wasted words or redundancy.

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

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

For a simple one-parameter tool with rich annotations and an output schema, the description fully covers purpose, usage, and relationships to related tools. It even includes the output format (eId + preview line), making it complete for an agent to select and invoke correctly.

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

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

The input schema fully describes the single 'slug' parameter with an example. The description adds value by explaining how to obtain the slug ('Call case_law_search FIRST to get the slug'), which is not in the schema. Since schema coverage is 100%, the baseline is 3, and the workflow hint lifts it to 4.

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

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

The description states 'get the paragraph navigation index (eId + preview line for every paragraph)' with a specific verb and resource. It clearly distinguishes from siblings by mentioning judgment_get_paragraph for full text and case_law_grep_judgment for content search.

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

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

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

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

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

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

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

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

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

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

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

With an output schema present and full annotations, the description still manages to provide essential workflow (call judgment_get_index first) and alternative search method. It is complete for the tool's complexity.

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

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

Schema coverage is 100% and includes a detailed eId description with normalization rule. The description itself doesn't add new parameter details beyond referencing them, so baseline 3 is appropriate.

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

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

The description clearly states the tool gets a judgment paragraph's full text given a slug and eId. It distinguishes from siblings by explicitly routing users to judgment_get_index for eIds and case_law_grep_judgment for content-based search.

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

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

Provides explicit when-to-use criteria ('when you have a judgment slug + LegalDocML eId and want that paragraph's full text') and names alternatives (judgment_get_index, case_law_grep_judgment). This is exemplary guidance.

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

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

Annotations only declare readOnly/idempotent/openWorld, but the description adds substantial operational context beyond them: content is capped by max_chars with a content_truncated flag, a not_found error is raised rather than returning a plausible-but-wrong node, and it warns that extent must be checked. These are behavioral traits the structured fields do not carry.

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

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

Front-loaded with the selection condition and organized into short paragraphs, each carrying actionable content (truncation, error behavior, extent caveat). Some overlap with the schema's own parameter text, so slightly longer than strictly necessary, but nothing is wasted.

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

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

An output schema exists so return fields need no re-explanation, yet the description still covers return format essentials (extent, in-force, prospective flag, content_truncated), error semantics, and the cross-noun invocation pattern. Complete for an agent to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: pass the bare number regardless of whether the document uses section/regulation/article, raise max_chars for unusually long Finance Act definitions, and always check the returned extent. It goes beyond restating the schema.

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

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

States a specific verb and resource ('get the parsed text of a specific section, regulation, or article') and explicitly scopes what is returned ('the provision's own text and its own heading — never a neighbouring or enclosing Part/Chapter's content'). This clearly distinguishes it from legislation_get_toc, legislation_search, and read_resource.

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

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

Opens with 'USE THIS TOOL WHEN you have a known Act / SI', names the alternative read_resource for raw CLML XML with the condition that selects it, and points to legislation_get_toc for valid numbers. When-to-use, when-not-to-use, and alternatives are all explicit.

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

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

Annotations cover safety (readOnly, idempotent, openWorld), so the lower bar applies. The description adds real behavioral context beyond that: pagination via offset/limit, has_more/total_items signals, document-order return, bare-id entries, and a critical downstream id-format rule. It doesn't describe the actual return shape in depth, but output schema exists and covers that.

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

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

Front-loaded trigger, then behavior, then alternative — well organized. Slightly long for the content, with examples that partially repeat schema-provided defaults, but every sentence carries information.

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

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

For a paginated read tool with annotations and an output schema, the description supplies the pagination model, the downstream id handoff, and the read_resource alternative. Complete enough to call correctly; only minor return-shape detail is left to the 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 description coverage is 100%, so the schema already documents offset, limit, year, number, type. The description adds the '47 not section-47' id-format rule, which is meaningful, but that concerns downstream passage rather than these parameters. Baseline 3 is correct since structured fields do the param work.

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

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

States a specific verb and resource ('get the structural table of contents') and explicitly scopes it to a known Act/SI. It contrasts directly with legislation_get_section and read_resource, so an agent can place it without opening any schema.

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

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

Explicit trigger ('WHEN you have a known Act / SI'), an explicit alternative (read_resource for the full non-paginated TOC), and the condition that selects each. The when-to-use-this-vs-alternative is fully resolved.

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 readOnly=true, openWorld=true, idempotent=true, destructive=false; the description adds concrete behavioral details: ranked results with fields (title, type, year, number, URL), next_steps hints, and the zeroing-out risk when filtering by a guessed year. There is no contradiction with annotations.

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

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

The description is dense but well-structured, front-loading the purpose in the first sentence and using bolded warnings and examples. Every sentence provides actionable guidance, and no filler or redundancy is present, despite 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?

The description fully covers what an agent needs to select and invoke the tool: when to use it, how to filter, what to expect in results, and how to chain it with sibling tools. With an output schema also present and comprehensive annotations, the description is contextually complete.

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

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

Even though schema coverage is 100%, the description enriches parameter semantics with strategic guidance: 'guessing a year and filtering by it zeroes results when wrong', the phrase-plus-read-year workflow, and clear guidance on when to set fulltext=True. This adds real decision-making value beyond the schema's field 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 opens with 'USE THIS TOOL WHEN searching UK Acts and Statutory Instruments by title, phrase, or full-text,' which specifies a concrete verb, resource, and scope. It clearly differentiates from sibling tools like case_law_search and bills_search_bills by targeting UK legislation, and from legislation_get_toc/section by focusing on search rather than drill-down.

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

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

It provides explicit usage guidance: 'USE THIS TOOL WHEN...', a chaining workflow ('AFTER calling, chain to legislation_get_toc then legislation_get_section'), and filter discipline ('Use only when you already know the value' for exact-match filters). It also offers alternative strategies for currency-driven and full-text queries, making when-to-use vs. alternatives clear.

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

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

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

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

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

The description is brief, direct, and free of unnecessary detail. Two sentences convey the action and the return format efficiently.

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

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

For a simple no-argument list operation, the description is sufficiently complete. It names the return type and the key fields, though it does not specify ordering or pagination, which are not critical here.

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

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

The tool takes no parameters, so the parameter semantics are trivially satisfied. The description does not need to elaborate on inputs.

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

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

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

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

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

The usage is implied by 'List all prompts', but there is no explicit guidance about when to prefer this over get_prompt or other listing tools. It is adequate but not fully explicit.

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

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

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

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

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

The description is two sentences with zero filler. The first sentence states the core purpose, and the second adds the crucial detail about output fields. It is front-loaded and every sentence earns its place.

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

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

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

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

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

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

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

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

The description states a specific action and target: 'List all available resources and resource templates.' It clearly distinguishes static resources (with 'uri') from templates (with 'uri_template'), which helps differentiate from siblings like read_resource that fetch a specific resource. The verb 'List' and the resource type are unambiguous.

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

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

The description clearly implies this tool is for enumeration, but it does not explicitly state when to use it over alternatives or mention any exclusion criteria. It does not say, for example, 'Use this to discover resources before calling read_resource.' While the purpose is clear, the guidance is implicit rather than explicit.

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

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

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

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

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

The description is front-loaded with the primary trigger in the first sentence, then returns, then ordering rules. It is compact and every sentence serves selection or invocation; no wasted preamble.

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

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

Given the annotations covering safety and the presence of an output schema, the description supplies everything needed: when to use it, what it returns, why disambiguation matters, and how it fits before ID-filtering sibling tools. No critical selection or invocation detail is missing.

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

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

Schema coverage is 100% and the parameter already has an example. The description adds meaning beyond the schema by clarifying that the name query may match multiple members, that common names need disambiguation, and that the result is an integer ID for downstream filtering.

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

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

The description states a specific verb and resource: find a Member of Parliament by name and return their integer member_id. It distinguishes itself from sibling tools that filter by member_id and from text-search alternatives, so an agent can select it without opening other schemas.

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

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

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

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

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

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

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

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

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

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

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

With an output schema present, return-value explanation is unnecessary, and the description still supplies the chaining path, volume expectations, and fallback behavior. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already fully documented (member_id semantics, debate_ext_id chaining, defaults, volume). The description restates the member_id filtering behavior rather than adding new syntax or format detail, so the baseline 3 applies.

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

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

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

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

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

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

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

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

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

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

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

The description is front-loaded with the usage condition and contains well-structured bullet points for the two IDs. It is longer than minimal but every sentence adds meaningful context; no waste.

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

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

Given the tool has an output schema, the description focuses on critical nuances: the possibility of an empty list, the meaning of votes_id, the cross-resolve behavior, and the None case. This provides a complete mental model for correct invocation and interpretation.

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

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

Schema coverage is 100% for the single parameter debate_ext_id, which already includes a detailed description with chaining sources. The tool description itself adds no additional parameter semantics beyond the usage line, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool retrieves divisions (formal votes) held within a debate. It distinguishes itself from siblings like parliament_get_debate_contributions and votes_get_division by focusing on the debate-level divisions list and explicitly referencing the votes_id linkage.

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

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

Explicitly says 'USE THIS TOOL WHEN you have a debate_ext_id and want the divisions'. Also provides when-not-to-use context (most debates have no divisions) and directs users to votes_get_division with the votes_id, giving clear alternative and follow-up guidance.

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

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

Annotations already cover read-only, idempotent, non-destructive. The description adds rich behavioral detail: resolution is not gated on publication state, empty matches typically mean volume_number is wrong or a Written Statement, and the warning not to interpret empty matches as fabrication. It also discloses the live verification that sitting date is not a substitute for volume. This exceeds what annotations provide.

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

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

The description is lengthy but well-structured: it leads with the primary usage, gives an example, then covers match fields, troubleshooting, and an authoritative note. Every section earns its place, though it could be tightened. The front-loading of 'USE THIS TOOL WHEN' is effective.

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

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

Given the output schema exists and annotations cover safety, the description is thorough: it explains match contents, source codes, failure modes, and how to proceed after a successful lookup. It also provides an alternative route to contributions, making it self-sufficient for an agent to call correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the string type for column_number (to handle suffixes like '1162W') and reinforcing that volume_number is mandatory and cannot be replaced by a date. It also links empty matches to likely incorrect volume_number, which aids parameter interpretation. This goes slightly beyond 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 opens with an explicit directive ('USE THIS TOOL WHEN you have an OSCOLA-style Hansard citation...') and a concrete example ('HL Deb 14 Oct 2025, vol 849, col 200'). It states the resource (Hansard column resolution) and the output (matches with contribution metadata), making the tool's purpose unambiguous and distinct from general search tools.

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

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

It clearly specifies when to use this tool: when you have a column+volume+house citation. It also gives a follow-up path (read_resource or parliament_get_debate_contributions) and troubleshooting for empty matches. However, it does not explicitly state when NOT to use it or name alternative tools like parliament_search_hansard or citations_resolve as competing options, so it falls short of the full 5.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), so the bar is lower, and the description adds genuine non-structured context: the verbatim text-body matching semantics, the 3000-char text cap, and the filtering consequence of missing tokens. It does not describe pagination behavior, though the schema's offset field partially covers that.

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

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

Front-loads the trigger condition, then prerequisites, then the key semantic caveat. Slightly redundant between the two verbatim-search explanations, but every sentence carries routing or behavioral weight.

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

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

Given an output schema exists and annotations cover safety, the description fills every remaining gap an agent needs: the prerequisite call, the text-matching semantics, the 3000-char cap, and the disambiguation from siblings. Nothing required to invoke correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description meaningfully augments the topic parameter by explaining what text is actually searched, what tokens to pass, and what not to pass ('not the bill's name'). This is additive semantic guidance beyond the schema's own prose.

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

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

States a specific verb+resource ('contributions where THAT member used a topic phrase verbatim') and explicitly distinguishes itself from the closest siblings parliament_search_hansard and parliament_get_debate_contributions. An agent can route correctly without opening schemas.

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

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

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

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

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

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

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

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

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

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

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

The tool is moderately complex with 5 parameters and pagination behavior, but the description fully covers when to use it, prerequisite steps, pagination, limits, and the authoritative nature of the data. An output schema exists, so return values needn't be detailed. This is complete for the agent to invoke correctly.

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

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

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

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

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

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

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

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

Usage is explicitly conditioned: 'USE THIS TOOL WHEN you have a member_id and need their registered financial interests.' It provides a clear prerequisite (call parliament_find_member first), directs away from web search due to stale data, and gives pagination guidance for prolific members. This is excellent when-to-use and alternative guidance.

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

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

Annotations declare readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false. The description adds behavior beyond that: it sweeps /search/Debates.json with pagination, states the hard cap semantics, discloses the rate limit ('1000 req/5min'), notes that by_party and top_contributors are deliberately omitted due to upstream limitations, and confirms 'no LLM, no editorial labels'. The omission disclosure is unusually valuable context.

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

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

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

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

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

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

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, including defaults, enums, and the rate-limit note in max_debates_scanned. The description briefly contrasts topic semantics with parliament_search_hansard.query (debate-level metadata matching vs body text), which is a small addition, but mostly repeats what the schema already says. Baseline 3 is appropriate.

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

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

The title and body state a specific verb (aggregate) and resource (Hansard debate-level signals on a topic), and it explicitly differentiates itself from text-search siblings (parliament_search_hansard) by describing the facet-aggregation output (by_house, by_year, by_section). The mention of 'authoritative source for UK Hansard corpus-level signals' anchors the scope.

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

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

The opening 'USE THIS TOOL WHEN...' clause states the trigger condition, and it names a clear follow-up ('pass debate_ext_id into parliament_get_debate_contributions') plus an alternative for member-level queries (hansard://debate/.../header or parliament_member_debates). It doesn't fully name what this tool is not for versus parliament_search_hansard, but the WHEN clause plus alternatives is strong.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, and the description adds real behavioral context on top: pagination semantics, the 3000-char cap in 'full' mode versus uncapped resource reads, the response metadata fields, and an explicit authority/anti-hallucination instruction.

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

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

Front-loaded with a clear 'USE THIS TOOL WHEN' opener, then delimited blocks for drill-down, exclusions, and pagination. Slightly verbose, and the resource-vs-tool equivalence is stated twice, but every block carries actionable routing 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 9 parameters, an output schema, and heavy annotation coverage, the description covers the remaining gaps: when to use it, when to use siblings instead, how to paginate, and how to expand results. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and the parameter docs are already rich, so the schema carries most weight. The description still adds routing semantics not in the schema — the limit+offset pagination framing and the member-name retrieval chain — but does not enrich individual field semantics much beyond that.

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

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

States a specific verb+resource+scope: searching Hansard debate text by topic, bill title, or phrase, and explicitly notes it is the authoritative source for UK parliamentary debates. It distinguishes itself from siblings by naming the drill-down and retrieval paths that are NOT this 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?

Gives explicit when-to-use (topic/phrase search), when-not (do not text-search by member name), and the exact alternative chain (parliament_find_member → parliament_get_debate_contributions). It also routes breadth queries to parliament_policy_position_summary and says not to supplement with web search.

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

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

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

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

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

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

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

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

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

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

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

Schema coverage is 100%, so the baseline is 3. The description mentions filtering by state but inconsistently lists 'debated' as an option while the schema enum only allows 'open', 'closed', and 'all', which could mislead. It does not add significant meaning beyond the schema's already descriptive parameter fields.

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

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

The description uses a specific verb ('search') and resource ('UK Parliament petitions') with clear scope ('by keyword or topic'). It distinguishes itself from sibling tools like parliament_search_hansard and bills_search_bills by focusing on petitions specifically.

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

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

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

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds valuable behavioral details: it clarifies return type (string) and base64 encoding for binary content, and explains templated resource handling. This exceeds annotation coverage and provides useful context without contradiction.

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

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

The description is three sentences, front-loaded with the core purpose. Each sentence earns its place: purpose, usage variation, and return format. No fluff or redundancy. Structure is clear and scannable.

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

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

The description covers the main usage scenarios (static and templated), return format, and binary handling. While it doesn't mention error handling or edge cases, for a generic read tool with an output schema and comprehensive annotations, it is adequately complete. The lack of sibling differentiation is a minor gap but not critical for the tool's own functionality.

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

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

The schema description for 'uri' is minimal ('The URI of the resource to read'), but the tool description significantly enriches meaning by explaining static vs templated URIs and the need to fill template parameters. This adds substantial semantic value beyond the schema, compensating for the schema's brevity.

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

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

The description states a clear verb and resource: 'Read a resource by its URI.' It precisely defines the action without ambiguity, and it differentiates itself from specialized siblings by being the generic resource reader, though it doesn't explicitly name alternatives. The purpose is immediately understandable.

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 instructions on how to provide the URI (static vs templated) but does not provide any guidance on when to use this tool versus the many specialized siblings (e.g., judgment_get_header, legislation_get_section). An agent cannot infer when to choose read_resource over a domain-specific reader, which is a significant gap.

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

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

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

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

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

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

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

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

With only two parameters and an existing output schema, the description covers all critical aspects: what the tool does, when to use it, key limitations (truncation), and how to obtain inputs. No additional context is needed for an agent to invoke it correctly.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

With an output schema present and 100% parameter schema coverage, the description only needs to supply usage context and behavior not already in structured fields. It does so thoroughly, covering search scope, pagination, what the response contains, and the follow-up tool to use. Nothing an agent needs to call this tool correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents every parameter. The description reinforces that search can be by topic, date, or member, but doesn't add new semantic details beyond what the schema provides. Per the baseline rule, 3 is appropriate.

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

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

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

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

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

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

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