UK Legal Research

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, lowering the bar for behavioral disclosure. The description adds useful context beyond annotations: results are a paginated page of bill summaries containing title, current stage, and Act status, and the tool is an authoritative source. 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 three sentences, front-loaded with the usage trigger, and every sentence earns its place: what the tool searches, what it returns, and what to do next. There is no filler 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?

Given the output schema exists, return values need no further explanation. The description covers search scope, result shape (paginated summaries with key fields), and the follow-up workflow to bills_get_bill, making it complete for a search tool of this complexity.

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

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

Schema coverage is 100%, with each parameter already well described in the input schema. The description only lightly reinforces that query/session/house/stage are the filter dimensions and adds no new parameter-level semantics. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description opens with 'USE THIS TOOL WHEN searching UK parliamentary bills' and names the exact resource (parliamentary bills) and filter dimensions (keyword, session, house, legislative stage). It clearly distinguishes itself from the sibling bills_get_bill by positioning search as the precursor and pointing to the get tool for full detail.

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

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

It provides an explicit trigger ('USE THIS TOOL WHEN') and clear context: searching UK parliamentary bills with optional filters. It also gives follow-up guidance to call bills_get_bill with a bill_id for full detail, which serves as an alternative. It does not explicitly state when not to use it relative to broader legislation_search, 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, 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?

The description richly discloses behavior beyond annotations: it performs a live TNA HEAD check, sets confidence to 0.0 on non-200, raises ToolError with a transient error category and retryable flag, and attempts one retry. These details are not present in the annotations and are critical for agent decision-making.

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

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

The description is front-loaded with a bold imperative, followed by concise actionable sections covering resolution behavior, error handling, and anti-fabrication guidance. Every sentence adds value; there is no repetition of schema/annotation content or filler.

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

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

For a network-dependent resolution tool, the description covers the full context: live verification, failure semantics, retry behavior, and the safe fallback when resolution fails. The presence of an output schema means return-value details need not be spelled out, and the description still provides enough for an agent to select and invoke the tool correctly.

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

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

The input schema already provides 100% coverage for the single parameter with examples. The description adds further semantic context by enumerating citation types ('neutral citation, SI, legislation section, retained EU law') beyond the schema examples, and explains the resolution behavior tied to the parameter, adding value over the schema baseline.

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+resource: 'Parses + resolves a single citation ... and returns parsed fields plus resolved_url.' It clearly distinguishes itself from siblings by instructing to use this tool BEFORE constructing an OSCOLA citation string from known fields, separating it from formatting and parsing tools.

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

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

The description explicitly states when to use the tool ('USE THIS TOOL BEFORE constructing an OSCOLA citation string from known fields, OR to confirm a citation points at a real document') and when not to ('Do NOT format or quote a confidence-0.0 citation'). It warns against fabrication but does not explicitly name alternative sibling tools, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, 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?

The description goes beyond the annotations (readOnly, idempotent, non-destructive) by disclosing pagination behavior (returns one page, default 20), caps on title length per max_title_chars, witness list cap at 10 per item, and the offset/has_more pagination pattern. These are valuable operational details not present in 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 concise and well-structured, with the directive 'USE THIS TOOL WHEN' front-loaded. Each sentence delivers a distinct piece of information: when to use, page size, caps, pagination loop, and authority. No filler or redundancy; 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?

Given the tool's complexity (5 parameters, pagination, caps), the description covers all essential behavioral aspects: pagination loop, cap behavior, and authoritative status. The presence of an output schema removes the need to describe return structure, and annotations already cover safety traits. Overall, the description is complete for effective tool invocation.

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

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

Schema coverage is 100%, so a baseline of 3 is appropriate. The description adds meaningful supplemental context by directly referencing max_title_chars for title capping and offset for pagination, explaining the split between oral and written evidence in the 'both' case, and reinforcing the limit/offset behavior. This adds value beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: retrieving oral and written evidence submitted to a committee given a committee_id. It uses a specific verb ('search') and resource ('committee evidence'), and distinguishes it from sibling tools like committees_get_committee and committees_search_committees by focusing on evidence retrieval rather than committee metadata.

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 'USE THIS TOOL WHEN' condition, providing clear context for when to invoke it. It also includes pagination guidance (re-call with offset while has_more) and notes the 'authoritative source' aspect. However, it does not explicitly mention alternatives or when not to use it, which prevents a top score.

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, and non-destructive behavior. The description adds value by disclosing the return format (JSON with a messages array) and the argument mapping requirement, which is beyond what annotations provide.

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

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

Three concise sentences, front-loaded with the main action. No redundancy or filler; each sentence provides useful information.

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

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

With a good annotations set and an output schema (mentioned in context), the description covers the essential aspects: what it does, how arguments are provided, and the return shape. Minor omission: no mention of error behavior (e.g., prompt not found), but not critical for a simple get operation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics by clarifying that arguments should be a dict mapping names to values, which is more specific than the schema's 'Optional arguments for the prompt'.

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 prompt by name with optional arguments, using the specific verb 'get' and naming the resource. It distinguishes itself from sibling tools like list_prompts by focusing on retrieving a single named 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 description implies usage: call it when you know the prompt's name and need its rendered content. It doesn't explicitly mention alternatives or exclusions, but the context is clear enough that users would understand it's for targeted retrieval, not listing.

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?

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses a critical behavioral trait: the tool uses a static lookup table current as of Nov 2023 and may be outdated. This is valuable context that helps the agent assess reliability and decide whether to cross-verify.

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 usage instruction. Each sentence provides distinct value: purpose, return contents, and caveat about data recency. 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?

For a simple one-parameter tool with rich annotations and an output schema, the description is thorough. It covers what the tool does, when to use it, what it returns, and a crucial limitation. No important context 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?

The input schema already provides 100% coverage with a clear description and examples for commodity_code. The tool description adds no additional parameter-level semantics, so the baseline of 3 applies as the schema carries the explanation burden.

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

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

The description clearly states the tool's purpose: to get the VAT rate category for a UK commodity or service description. It specifies the exact output (standard/reduced/zero/exempt rates, effective date, conditions) and distinguishes itself from sibling tools like hmrc_search_guidance, which is for general guidance lookups.

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' to explicitly define the intended use case. It also provides an alternative for time-sensitive advice, directing users to hmrc_search_guidance, which qualifies as explicit when/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 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 already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations: content truncation via max_chars, the content_truncated response field, and the extent-check warning. It also mentions the 'prospective flag' as an output trait, so the agent knows what to expect.

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

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

The description is front-loaded with a bolded 'USE THIS TOOL WHEN' and organized into clear paragraphs. It is somewhat wordier than necessary (e.g., repeating default token count), but every section serves a distinct purpose—purpose, return details, warning, alternative—making it efficient 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 description is complete for a read tool with an output schema: it covers the intended use case, key output fields (extent, in-force, prospective flag), truncation behavior, a critical legal-research caution, and an explicit alternative. It also tells the user to get type/year/number from legislation_search, which is helpful. Nothing essential 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% with detailed descriptions for every parameter, including max_chars default and guidance to check content_truncated. The description adds minimal extra meaning beyond schema, mostly reiterating the max_chars behavior. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the tool's function: 'USE THIS TOOL WHEN you have a known Act / SI and want the parsed text of a specific section, with extent and in-force metadata.' This specific verb+resource+outcome distinguishes it from siblings like legislation_get_toc and read_resource, and it explicitly contrasts with the raw XML alternative.

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 usage guidance: when to use the tool ('when you have a known Act / SI'), what to check ('ALWAYS check extent'), and names the alternative ('call read_resource(uri=...) for raw CLML XML'). This is a clear when/when-not with 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 indicate read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context: pagination via offset/limit, has_more/total_items fields, and a note about stripping the 'section-' prefix when passing IDs to legislation_get_section.

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 an explicit use case and is well-structured into purpose, return elements, pagination, and alternative. It is longer than strictly necessary, but each sentence adds value and the structure helps an agent parse it.

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

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

Given the tool's complexity (5 parameters, pagination, output schema), the description covers the essential context: when to use it, how pagination works, what the returned elements look like, and how the output relates to sibling tool legislation_get_section. With annotations and output schema present, this is sufficiently complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some pragmatic guidance (e.g., 'Use the value from legislation_search results' for type, and check has_more/total_items for pagination), but these mostly reinforce the schema rather than providing new semantics.

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

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

The description states a specific purpose: retrieving the structural table of contents for a known Act/SI, enumerating parts, chapters, sections, schedules. It clearly distinguishes this from sibling tools like legislation_get_section 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?

It explicitly says 'USE THIS TOOL WHEN you have a known Act / SI and want the structural table of contents'. It also provides an alternative (read_resource) and explains when to choose this tool over that alternative (when structured response with pagination is needed).

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

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

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that the tool returns JSON with prompt metadata, but provides no additional behavioral details such as pagination or rate limits. Minimal added value beyond the annotations.

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

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

The description is two sentences, front-loaded with the core action 'List all available prompts', and includes a brief note on return format. There is 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?

For a zero-parameter list tool with comprehensive annotations and an available output schema, the description is complete. It states the purpose and the general shape of the return value, without needing to list fields.

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

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

The tool has zero parameters and schema description coverage is 100%, so the schema fully documents parameters. Per the rubric, 0 params yields a baseline of 4. The description needs no further parameter explanation.

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

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

The description clearly states the verb 'List' and resource 'all available prompts', which distinguishes it from sibling get_prompt. It also specifies the return format (JSON with metadata), leaving no ambiguity about the tool's function.

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 phrase 'List all available prompts' provides clear context: use this when you need to enumerate all prompts. It does not explicitly mention alternatives like get_prompt, but the scope is unambiguous for a simple list operation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable contextual detail by specifying that the output is JSON with metadata, and that static resources have a 'uri' field while templates use a 'uri_template' field with placeholders. This goes beyond what annotations provide.

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

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

The description is two sentences, with the primary action in the first sentence and a concise elaboration of the return format in the second. Every word adds value, and there is no filler or repetition.

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

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

For a zero-parameter listing tool, the description is complete. It covers the resource types (static vs. templates) and the field naming convention. The presence of an output schema handles detailed return structure, and annotations cover behavioral traits, so no other context is needed.

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 parameter semantics are trivially satisfied by the schema. According to the baseline for 0 params, a score of 4 is appropriate. The description does not attempt to document nonexistent parameters, but it does clarify the output structure, which is not parameter-related.

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

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

The description clearly states the tool lists all available resources and resource templates, using the specific verb 'List' and naming the resource type. It distinguishes from sibling tools like read_resource by the broader scope of 'all available resources and templates'.

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 the tool is for enumerating resources, but it does not explicitly provide when-to-use or when-not-to-use guidance, nor does it mention alternatives such as read_resource or list_prompts. The context is clear but no exclusions are stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive hints, and the description adds valuable behavioral context: returns all matches with listed fields, handles common-name disambiguation (e.g., 'Lord Smith'), and does not contradict annotations.

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

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

The description is front-loaded with the critical usage directive, then concisely details return behavior, disambiguation, and prerequisite relationships. Every sentence earns its place; there is no fluff despite the 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?

Although an output schema exists, the description enriches the context by explaining the tool's role in the broader workflow, return content, and disambiguation behavior. It sufficiently covers all details needed for correct selection and 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?

The input schema covers 100% of the single parameter with a clear description and examples ('Starmer', 'Baroness Hale'). The tool description adds no additional parameter semantics beyond reinforcing the name-to-ID purpose, so the high schema coverage 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 resolves a member's name to an integer member_id, with a clear verb and resource. It distinguishes it from sibling tools by framing it as a prerequisite lookup for member_id-based filtering, unlike direct 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?

Provides an explicit 'USE THIS TOOL WHEN' instruction and names specific alternatives to call before (parliament_get_debate_contributions, etc.). It also gives a negative example (text-searching by name returns unrelated results) and references the Pannick case, making when/when-not boundaries very clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavioral context: without member_id it returns ~100-200 contributions, and it explicitly warns to report empty results honestly rather than reconstructing quotes from training data. This goes beyond the annotations and helps the agent set expectations correctly.

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

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

The description is longer than average but every sentence earns its place: usage trigger, differentiation, canonical chain, default behavior, and integrity warning. It is front-loaded with the key instruction and structured logically, so the length is justified.

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

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

For a tool with only two parameters and an output schema present, the description covers all necessary context: when to use, how to chain, default output size, member filtering behavior, and a critical honesty constraint. Nothing essential is missing; it fully equips the agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, and the description further adds meaning beyond the schema. It clarifies that member_id filtering works 'regardless of which words they used' and how debate_ext_id is obtained via chaining from search tools. The parameter semantics are fully enriched.

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 verb and resource: 'get debate contributions' with optional member filter. It explicitly distinguishes itself from sibling tools like parliament_member_debates and parliament_search_hansard by emphasizing 'verbatim contributions' and filtering by MemberId rather than text. This makes the tool's unique purpose unmistakable.

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?

Directly states 'USE THIS TOOL WHEN you have a debate_ext_id and want verbatim contributions,' and explains when not to use text-search alternatives: 'text-search tools filter by contribution TEXT, dropping members who spoke without using your phrase verbatim.' It also provides a typical chain with other tools, offering clear context and exclusion criteria.

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?

The annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the bar is lower. The description adds meaningful behavioral context: resolution is not gated on publication state, empty matches typically indicate a volume-number issue or written statement rather than a fabricated citation, and the failure should be surfaced. This goes well beyond the annotations without contradicting them.

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

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

The description is front-loaded and well-structured with clear sections, and most sentences earn their place. The closing 'Authoritative source' line is somewhat rhetorical and the 'Each match carries' section may duplicate output schema details, making it slightly longer than necessary while still being coherent.

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 and rich annotations, the description is complete: it tells the agent exactly when to invoke, how to interpret matches, what empty results mean, and what follow-up actions to take. It also differentiates itself from sibling tools well enough for correct selection.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by providing a concrete OSCOLA example, emphasizing that volume_number is required and a sitting date is not a substitute, and explaining that column_number is a string to accommodate suffixes like '1162W'. This goes beyond the schema's field-level descriptions.

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

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

The title and opening line clearly define the tool's purpose: resolving an OSCOLA-style Hansard citation to the corresponding debate. It explicitly distinguishes this from search-oriented siblings like parliament_search_hansard by naming the exact input form (column + volume + house).

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 an OSCOLA-style Hansard citation') and provides specific follow-up alternatives (read_resource or parliament_get_debate_contributions). However, it does not explicitly enumerate when-not-to-use cases relative to sibling search tools, so it doesn't reach the maximum.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior, but the description adds valuable context: text-body search semantics, filtering of members who didn't use the phrase, the 3000-character cap on contribution text, and the prerequisite of obtaining member_id. This goes beyond the annotations to explain real behavioral constraints.

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

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

The description is front-loaded with a clear usage directive, followed by a prerequisite, then semantic clarification and an alternative. Each sentence serves a distinct purpose; the length is justified by the tool's complexity and the need to prevent misuse.

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

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

For a read-only, well-annotated tool with a rich output schema, the description covers all necessary context: when to use, prerequisites, search semantics, limitations (3000-char cap), and the alternative for complete retrieval. No gaps are evident.

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

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

While schema coverage is 100%, the description adds significant meaning, especially for the 'topic' parameter: it clarifies that the search targets the member's actual spoken words, not debate titles, and gives examples of effective search tokens. It also explains offset pagination behavior, enriching the schema's basic 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 clearly identifies the tool's purpose: retrieving contributions where a specific member used a specific topic phrase verbatim in a text-body search. It distinguishes from the sibling tool parliament_get_debate_contributions by clarifying this is a name-based text-body search, not a full debate retrieval.

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

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

The description explicitly states when to use this tool ('USE THIS TOOL WHEN you have a member_id and want contributions where THAT member used a specific topic phrase verbatim'), requires calling parliament_find_member first, and names the alternative tool for retrieving all contributions regardless of vocabulary. This is 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?

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?

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses pagination behavior ('Sweeps /search/Debates.json with pagination'), the API rate limit ('1000 req/5min'), and a key data limitation ('Hansard's search API exposes debate metadata, not per-contribution member identifiers'). It also explains why certain facets are omitted (by_party, top_contributors), providing valuable context for the agent.

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 relatively long but well-structured with a clear 'USE THIS TOOL WHEN' opener and separate paragraphs for behavior, follow-up, and limitations. Each section serves a distinct purpose, though the final sentence ('This is the authoritative source...') adds marginal value and could be considered redundant. Still, 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 description is exceptionally complete for a complex tool. It explains the input semantics, processing pipeline, output facets, data limitations, and how to proceed after calling. It also references related resources (hansard://debate/...) and alternative tools. With an output schema present, the description does not need to enumerate return fields, but it still gives a clear picture of what the tool returns.

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

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

Although schema coverage is 100%, the description adds significant semantic nuance beyond the schema. It explains the `topic` parameter's relationship to parliament_search_hansard.query and clarifies why Bill titles work for this tool despite not working for text search, due to debate-level metadata matching. It also maps max_debates_scanned to upstream call counts and rate limits, enriching 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 opens with a clear directive ('USE THIS TOOL WHEN you want debate-level corpus signals on a topic') and specifies the exact aggregations ('by_house, by_year, by_section breakdowns'). It distinguishes itself from siblings by stating it provides 'Pure counts — no LLM, no editorial labels' and explicitly contrasts with tools like parliament_get_debate_contributions that drill into contributions.

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

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

The description explicitly says when to use this tool ('when you want debate-level corpus signals... without reading every contribution') and gives follow-up actions ('AFTER calling, pick a debate from top_debates and pass its debate_ext_id into parliament_get_debate_contributions'). It also names alternatives for member-level queries ('call parliament_member_debates' or read the debate header).

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, openWorldHint, idempotentHint, and destructiveHint=false; the description is fully consistent with these. It adds valuable behavioral context: tokenized matching behavior, the fact that bill titles often don't match, pagination semantics (limit/offset, has_more), text_mode character caps, and the corpus envelope being independent of contribution_type. This goes well beyond the annotations.

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

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

The description is lengthy but each sentence serves a purpose: usage scope, return metadata, drill-down, exclusions, pagination, alternatives, and authority. It is front-loaded with the key directive and structured with clear separations. Slight redundancy exists (e.g., 'USE THIS TOOL WHEN' restates the title), but overall it is well-organized and earns 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?

Given 9 parameters, rich annotations, an output schema, and multiple related siblings, the description covers all critical contexts: when to use, when not to use, how to paginate, how to retrieve full text, what each contribution_type means, and the authoritative nature of the data. It also points to the workflow for member-specific queries. This is fully 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%, but the description enriches the query parameter with practical guidance (e.g., 'Pass tokens that would appear in someone's speech', 'Bill titles often DON'T match'). It also clarifies member_id (integer ID, not name string, with explanation of the old field), text_mode, and contribution_type semantics. This is high-value elaboration beyond bare 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 specific directive: 'USE THIS TOOL WHEN searching Hansard by topic, bill title, or text phrase.' It clearly identifies the resource (Hansard debates) and the action (search), and distinguishes from sibling tools by contrasting with parliament_get_debate_contributions and parliament_find_member. The stated purpose is unambiguous and technically accurate.

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 'DO NOT' guidance ('DO NOT text-search by member name') and names the correct alternative workflow (parliament_find_member → parliament_get_debate_contributions). It also mentions parliament_policy_position_summary for broad topic scans and gives a concrete drill-down path via read_resource. This is exemplary usage 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 declare readOnlyHint and idempotentHint, so the bar is lower. The description adds valuable context about return fields (title, state, signature count, dates) and the authoritative source, but does not disclose behavioral details like pagination or rate limits.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already declare the operation as read-only and idempotent. The description adds value by specifying the return type (string), base64 encoding for binary content, and how templated URIs should be handled. It does not disclose error behavior, but that is not required given the annotation coverage.

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

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

Three sentences, front-loaded with the core action ('Read a resource by its URI'), followed by necessary usage nuance and return format. Every sentence earns its place with 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?

For a tool with one parameter, full schema coverage, and an output schema, the description is sufficient. It explains how to invoke for both resource types and what to expect in the response. The output schema is provided separately, so no need to duplicate that.

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

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

The schema fully documents the 'uri' parameter, so the baseline is 3. The description enriches this by explaining static vs templated resource usage and the need to fill in template parameters, adding semantics beyond the schema's one-line 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 uses a specific verb ('Read') and resource ('a resource by its URI'), clearly distinguishing it from sibling tools that target specific domains (e.g., bills_get_bill). It is generic but unambiguous, making its purpose immediately clear.

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

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

Provides clear context for when to use the tool: when you have a URI and need its content. It distinguishes between static and templated resources, which is useful practical guidance, though it does not explicitly name alternatives or exclusions.

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

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

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 cover readOnly, idempotent, and non-destructive behavior. The description adds useful context beyond annotations: the output contains summaries (title, date, vote counts, pass/fail) and that it is the authoritative source for UK parliamentary vote records.

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 usage directive. Every sentence adds value: search scope, return summary, downstream handoff, and authoritative source, with 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?

For a 7-parameter tool with a complete schema, rich annotations, and an output schema, the description sufficiently covers when to use it, what it returns, and how to proceed with results. It provides the necessary context for correct selection and 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 parameters are already well-documented. The description reinforces the mapping of 'topic, date, or member' to query/date/member_id, but adds no new parameter-level details beyond the schema.

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

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

The description explicitly states the tool searches Commons or Lords formal votes by topic, date, or member, and clarifies it returns division summaries. It distinguishes itself from the sibling votes_get_division by noting the downstream call for full voter lists.

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

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

It leads with 'USE THIS TOOL WHEN' and specifies the exact search dimensions. It also explicitly instructs the agent to pass division_id and house into votes_get_division afterward, providing clear complementary usage guidance.

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