UK Legal Research

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

Annotations already cover key behavioral traits (read-only, idempotent, non-destructive, open-world), so the bar is lower. The description adds value by specifying the return content (sponsors, stage history, etc.) and the Royal Assent condition, which provides useful context beyond annotations. No contradiction with annotations is present.

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

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

The description is appropriately sized and front-loaded: the first sentence states the core purpose, followed by specific return details and parameter guidance. Every sentence adds value with no waste, and the structure is clear and efficient.

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

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

Given the tool's low complexity (1 parameter), rich annotations, and the presence of an output schema (which handles return values), the description is complete. It covers purpose, usage context, parameter details, and return content, leaving no significant gaps for the agent.

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

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

Schema description coverage is 0%, so the description must compensate. It explicitly defines the single parameter (bill_id) and its source (bills_search_bills results), adding crucial meaning not in the schema. This fully addresses the parameter semantics gap, making it highly effective.

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 with a specific verb ('Get') and resource ('full detail for a specific parliamentary bill'), distinguishing it from siblings like bills_search_bills (which searches) and other parliamentary tools. It explicitly lists the types of details returned, making the scope unambiguous.

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

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

The description provides clear context for when to use this tool: to retrieve detailed information for a specific bill, with the bill_id sourced from bills_search_bills. However, it does not explicitly state when not to use it or compare it to alternatives beyond the implied sibling relationship, missing explicit 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?

The description adds valuable context beyond annotations: it specifies the return format ('JSON array of BillSummary objects') and clarifies the scope of information returned ('bill summaries' vs 'full detail'). While annotations already indicate read-only, open-world, idempotent, and non-destructive behavior, the description provides practical implementation details that enhance transparency.

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

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

The description is perfectly structured and front-loaded: the first sentence states the core functionality, the second describes returns, the third provides usage guidance, and the final two lines document parameters and returns. Every sentence earns its place with zero wasted words.

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

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

Given the tool's moderate complexity, rich annotations, comprehensive input schema with excellent property descriptions, and explicit output schema reference, the description provides complete context. It covers purpose, usage guidelines, return format, and relationship to sibling tools, making it fully adequate for agent understanding.

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

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

With 0% schema description coverage, the description carries the full burden of explaining parameters. It mentions the main parameter ('params (BillSearchInput)') and lists the search criteria ('keyword, session, house, or legislative stage'), but doesn't provide detailed semantics for each field. The schema itself has excellent descriptions for all properties, so the description adds only moderate value beyond what's already in the structured 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 specific action ('Search UK parliamentary bills') and resources ('by keyword, session, house, or legislative stage'), distinguishing it from sibling tools like 'bills_get_bill' which provides full detail. It explicitly mentions what it returns ('bill summaries including title, current stage, and whether it has become an Act'), making the purpose unambiguous.

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

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

The description provides explicit guidance on when to use this tool versus alternatives: 'Use bills_get_bill with the bill ID for full detail including sponsors and stage history.' This clearly distinguishes it from its sibling tool and helps the agent understand the scope and limitations of this search function.

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

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

The description adds valuable behavioral context beyond annotations: it explains the truncation behavior controlled by max_chars, mentions the default is optimized for LLM context budgets, and describes the return structure. While annotations cover safety (readOnlyHint=true, destructiveHint=false), the description provides practical implementation details that help the agent understand how to work with the tool effectively.

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 appropriately sized, with the core purpose stated first followed by implementation details. While slightly verbose in explaining FastMCP patterns, most sentences add value for agent understanding. It could be slightly more concise in the returns section.

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 (XML retrieval with truncation), the description provides complete context: it explains the purpose, parameters, return structure, error handling, and implementation patterns. With annotations covering safety aspects and an output schema presumably documenting the return dict structure, the description fills all necessary gaps for effective tool use.

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

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

With 0% schema description coverage, the description fully compensates by explaining both parameters thoroughly: it clarifies that 'uri' is a TNA slug and should come from case_law_search, and explains 'max_chars' controls payload size with practical examples of default and higher values. The description adds significant meaning beyond the bare 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 specific action ('Retrieve'), resource ('full LegalDocML XML for a judgment'), and key identifier ('by TNA URI slug'). It distinguishes itself from sibling tools like 'case_law_search' by focusing on fetching full judgment text rather than searching for cases.

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

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

The description provides clear context about when to use this tool (to get full judgment XML) and references 'case_law_search' as the source for URIs. However, it doesn't explicitly state when NOT to use it or compare it to other potential alternatives beyond the sibling reference.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true. The description adds valuable behavioral context beyond annotations: it discloses pagination behavior ('paginated judgment summaries'), clarifies the relationship with sibling tool for full text retrieval, and describes the return format structure. However, it doesn't mention rate limits, authentication needs, or error conditions.

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 perfectly structured and concise: first sentence states purpose, second describes returns, third provides usage guidance, then clearly separated Args and Returns sections. Every sentence earns its place with zero 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 comprehensive annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), an output schema (Returns section details JSON structure), and clear sibling differentiation, the description provides complete context. It covers purpose, usage guidance, parameter overview, and return format without needing to repeat what's already in structured fields.

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

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

Schema description coverage is 0%, so the description carries full burden for parameter documentation. The description lists the parameters (query, optional filters: court, judge, party, from_date, to_date, page number) and provides some semantic context about what they filter. However, it doesn't explain parameter formats, constraints, or provide examples beyond what's implied. The schema itself has good descriptions, but with 0% coverage in the context signals, the baseline expectation is higher.

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 specific action ('Search UK case law via the TNA Find Case Law API'), resource ('UK case law'), and scope ('returns paginated judgment summaries'). It distinguishes from sibling tool 'case_law_get_judgment' by explaining this tool returns summaries while that one fetches full text.

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

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

The description explicitly provides when-to-use guidance: 'Use case_law_get_judgment with the returned uri to fetch full text.' This clearly indicates this tool is for search/summaries while the sibling is for detailed content, providing clear alternative usage.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and behavior. The description adds valuable context beyond annotations by specifying that it fetches XML from TNA, parses OSCOLA citations, and groups results by type, which helps the agent understand the tool's operational flow and output 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 appropriately sized and front-loaded, starting with a high-level purpose, followed by implementation details, and ending with return values. Every sentence earns its place by conveying essential information without redundancy, such as specifying the data source (TNA), parsing method (OSCOLA), and output format (JSON with grouped citations).

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 (parsing citations from XML) and the presence of an output schema (implied by the Returns section detailing JSON structure), the description is complete enough. It covers purpose, usage, parameters, and return values, while annotations handle behavioral traits. No gaps remain for effective agent use.

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

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

Schema description coverage is 0%, so the description carries full burden. It effectively compensates by clearly explaining the 'case_uri' parameter in the Args section, providing examples ('uksc/2024/12'), usage instructions ('Use the 'uri' field from case_law_search results'), and formatting rules ('Do not include the full URL prefix'). This adds significant meaning beyond the basic schema.

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

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

The description clearly states the tool's purpose with specific verbs ('Map all citations', 'Fetches the judgment XML', 'parses all OSCOLA citations') and resources ('within a judgment', 'cases cited, legislation referenced, SIs, EU law'). It distinguishes from sibling tools like 'citations_parse' and 'citations_resolve' by focusing on network mapping rather than parsing or resolving individual 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?

The description provides clear context for when to use this tool ('Map all citations within a judgment') and implies usage by mentioning it fetches from TNA and parses OSCOLA citations. However, it does not explicitly state when not to use it or name specific alternatives among siblings, such as 'case_law_get_judgment' for raw judgment data or 'citations_parse' for individual citation parsing.

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, indicating a safe read operation. The description adds valuable behavioral context: it explains the optional LLM disambiguation for ambiguous citations, mentions resolution to URLs (TNA/legislation.gov.uk), and describes the JSON return structure. This goes beyond what annotations provide without contradiction.

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

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

The description is efficiently structured: it starts with the core purpose, lists supported citation types with examples, explains optional disambiguation, mentions URL resolution, and clearly documents parameters and return value. Every sentence adds essential information 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?

Given the tool's complexity (parsing multiple citation types with optional disambiguation), the description is complete: it covers purpose, supported formats, behavioral details, parameters, and return format. With an output schema present, it appropriately omits detailed return value explanations, focusing on high-level JSON structure.

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

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

Schema description coverage is 0%, so the description carries full burden. It effectively explains both parameters: 'text' is described with examples of supported citation types and a length constraint, and 'disambiguate' is clearly defined with its boolean role in LLM sampling. This compensates well for the lack of 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 specific action ('extract and classify') and resource ('OSCOLA legal citations from free text'), with detailed examples of citation types. It distinguishes itself from sibling tools like citations_resolve or citations_network by focusing on parsing rather than resolution or network analysis.

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 context by listing supported citation types, but does not explicitly state when to use this tool versus alternatives like citations_resolve or legislation_search. No guidance on prerequisites or exclusions is provided.

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

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

The description adds valuable behavioral context beyond annotations: it specifies that the tool returns a resolved_url 'if resolvable' and may return an error otherwise, clarifying the conditional nature of the response. Annotations already indicate it's read-only, non-destructive, and idempotent, but the description enhances this by detailing the tool's scope (single citation) and output behavior, though it doesn't mention rate limits or auth needs.

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 core purpose in the first sentence, followed by supporting details (scope, return behavior) and a clear Args/Returns section. Every sentence earns its place by adding necessary information without redundancy, making it efficient and well-structured for quick comprehension.

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

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

Given the tool's moderate complexity (parsing and resolving citations), the description is complete: it covers purpose, usage, parameter semantics, and output behavior. With annotations providing safety hints and an output schema likely detailing ParsedCitation structure, the description doesn't need to explain return values further, making it adequately comprehensive for the context.

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

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

With 0% schema description coverage (the schema only defines the parameter structure without describing the citation input), the description fully compensates by explaining the parameter's purpose: 'A single OSCOLA citation to parse and resolve', with examples like '[2024] UKSC 12'. This adds essential meaning beyond the bare schema, ensuring the agent understands what to provide.

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 with specific verbs ('parse and resolve') and resource ('a single OSCOLA citation'), distinguishing it from sibling tools like citations_parse (which likely only parses) and citations_network (which likely handles multiple citations). It explicitly mentions the target formats (neutral citations, SIs, legislation sections, retained EU law) and the output (canonical URL), making the purpose unambiguous and distinct.

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

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

The description provides clear context for when to use this tool: for resolving a single OSCOLA citation to a URL, with examples of supported citation types. However, it does not explicitly state when not to use it or name alternatives (e.g., citations_parse for parsing without resolution, or other tools for non-OSCOLA citations), which prevents a perfect 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?

The description adds valuable behavioral context beyond annotations: it mentions that metadata and member list are fetched 'in parallel,' which is not covered by annotations like readOnlyHint or idempotentHint. This enhances understanding of performance or implementation details. No contradiction with annotations 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 appropriately sized and front-loaded: the first sentence states the core purpose, followed by implementation details and parameter/return info. Every sentence adds value without redundancy, 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?

Given the tool's complexity (1 parameter, nested objects, output schema), the description is complete enough. It covers purpose, usage context, behavioral traits, and parameter semantics. With an output schema present, it need not explain return values in detail, and annotations provide safety and idempotency info.

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

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

With 0% schema description coverage, the description compensates by explaining the parameter semantics: it clarifies that committee_id comes from committees_search_committees results, adding meaning beyond the bare schema. However, it does not detail the structure or format of the input object (CommitteeDetailInput), leaving some gaps.

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: 'Get detail for a parliamentary committee including current membership.' It specifies the verb ('Get'), resource ('parliamentary committee'), and scope ('including current membership'), and distinguishes it from sibling tools like committees_search_committees by focusing on detailed retrieval rather than searching.

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

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

The description provides clear context for usage: it references committees_search_committees as the source for committee_id, indicating when to use this tool (after obtaining an ID from search). However, it does not explicitly state when not to use it or name alternatives beyond the implied search tool, keeping it from a perfect 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?

The description adds valuable behavioral context beyond what annotations provide. While annotations cover read-only, open-world, idempotent, and non-destructive characteristics, the description adds that filtering is 'client-side against committee names' and clarifies the return format ('JSON array of CommitteeSummary objects'). This provides useful implementation details not captured in 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 perfectly structured and concise with zero wasted words. It opens with the core purpose, immediately provides key behavioral information (what's returned), gives usage guidance, then documents parameters and return format. Every sentence serves a distinct purpose and contributes to understanding.

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

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

Given the tool's moderate complexity, comprehensive annotations, and the presence of an output schema, the description provides complete contextual information. It covers purpose, usage guidelines, behavioral details, and parameter overview while leveraging the structured fields for technical specifications. The combination of description and structured data leaves no gaps for agent understanding.

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

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

With 0% schema description coverage, the description carries the full burden of parameter documentation. It mentions 'optional query, house, active_only filters' which covers the three parameters, but provides minimal semantic detail about what each filter does. The schema itself has good descriptions for each parameter, but the description text adds only basic identification without deeper meaning.

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

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

The description clearly states the specific action ('Search or list'), resource ('UK parliamentary select committees'), and scope ('committee names, house, and active status'). It explicitly distinguishes from the sibling tool 'committees_get_committee' by indicating that tool should be used for membership detail, establishing clear differentiation.

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

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

The description provides explicit guidance on when to use this tool versus alternatives: 'Use committees_get_committee with the committee ID for membership detail.' This directly addresses sibling tool differentiation and gives clear context for when to choose each tool.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true. The description adds useful context about what types of evidence are searched (oral/written/both) and what data is returned (titles, dates, witness names), which goes beyond the annotations. However, it doesn't mention rate limits, authentication needs, or pagination behavior.

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

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

The description is perfectly structured: first sentence states purpose, second describes returns, third specifies parameters, fourth specifies return format. Every sentence adds value with zero waste, and it's 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?

Given the annotations cover safety/behavioral aspects (read-only, non-destructive, idempotent), the input schema fully defines parameters, and there's an output schema (implied by 'Returns: str: JSON array of EvidenceItem objects'), the description provides complete context. It explains what the tool does, what it returns, and parameter basics without needing to duplicate structured data.

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 0%, but the description provides a high-level overview of parameters ('committee_id and evidence_type filter') and mentions the committee_id source. However, it doesn't explain parameter semantics in detail beyond what's implied. With 0% schema coverage, the description partially compensates but leaves gaps about specific parameter behaviors.

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 specific action ('Search oral and written evidence'), the resource ('submitted to a parliamentary committee'), and the return data ('evidence titles, dates, and witness names'). It distinguishes itself from sibling tools like 'committees_search_committees' by focusing on evidence rather than committees themselves.

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

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

The description implies usage when searching for committee evidence, but provides no explicit guidance on when to use this tool versus alternatives like 'committees_get_committee' or 'committees_search_committees'. It mentions the committee_id comes from 'committees_search_committees results', which is helpful but doesn't constitute full usage guidelines.

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

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

The description adds valuable behavioral context beyond what annotations provide: it specifies the default sandbox environment, how to switch to production, authentication requirements (OAuth 2.0 with specific env vars), and what data is returned. While annotations cover read-only, open-world, idempotent, and non-destructive properties, the description adds practical implementation details that help the agent use the tool 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 efficiently structured with a clear purpose statement upfront, followed by important notes about environment and authentication, then parameter and return value documentation. Every sentence serves a distinct purpose with no redundancy, and the information is well-organized for quick comprehension.

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

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

Given the tool's moderate complexity (API integration with authentication), the description provides complete context: purpose, environment configuration, authentication requirements, parameter details, and return value information. With annotations covering safety properties and an output schema presumably documenting the JSON structure, the description fills all necessary gaps without duplicating structured data.

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

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

With 0% schema description coverage for the single parameter, the description fully compensates by clearly explaining the 'vrn' parameter in the Args section: it specifies it's a 9-digit VAT Registration Number, mentions GB prefix handling, and provides an example. This adds crucial meaning beyond the bare schema that only defines string constraints.

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 specific action ('Check'), resource ('business's Making Tax Digital VAT mandate status'), and method ('via the HMRC API'). It distinguishes this tool from sibling tools like 'hmrc_get_vat_rate' and 'hmrc_search_guidance' by focusing on MTD status verification rather than VAT rates or guidance 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?

The description provides clear context about when to use this tool (to check MTD VAT status for a business) and includes important prerequisites (environment variables for OAuth 2.0). However, it doesn't explicitly state when NOT to use it or name specific alternatives among the sibling tools, though the purpose clearly differentiates it from other HMRC 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?

The description adds valuable behavioral context beyond what annotations provide. While annotations already indicate read-only, non-destructive, and idempotent operations, the description reveals that it 'Uses a static lookup table current as of 22 Nov 2023' and has data currency limitations. This disclosure about the static nature and potential staleness of data is crucial context not captured in annotations.

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

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

The description is well-structured and appropriately sized. It front-loads the core purpose, follows with return details, then important behavioral context about data currency, and finally includes parameter and return value documentation. Every sentence adds value with zero waste 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 tool's moderate complexity (single parameter, static lookup), the description provides complete context. It explains what the tool does, what it returns, important limitations about data currency, and parameter semantics. With annotations covering safety aspects and an output schema presumably documenting the return structure, the description adds all necessary contextual information.

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

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

With 0% schema description coverage for the single parameter, the description must compensate. It provides meaningful context by explaining that 'commodity_code' can be either 'Commodity code or plain-English description' and gives examples like 'food', 'domestic fuel', 'software'. This significantly enhances understanding beyond the bare schema, though it doesn't fully document all possible values or constraints.

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 with specific verb ('Look up') and resource ('UK VAT rate for a commodity or service type'). It distinguishes itself from sibling tools by focusing on VAT rate lookup, while siblings like 'hmrc_check_mtd_status' or 'hmrc_search_guidance' serve different HMRC-related functions.

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

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

The description provides clear context for when to use this tool (looking up VAT rates) and includes an important caveat about data currency ('Rates may have changed — always verify against GOV.UK for recent Budgets'). However, it doesn't explicitly state when NOT to use this tool or name specific alternatives among the sibling 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 provide readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds valuable context beyond annotations by specifying it searches 'the official GOV.UK content API filtered to HMRC publications' and describes the return format (titles, URLs, summaries, dates), which helps the agent understand the tool's behavior and output 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 perfectly structured and front-loaded: the first sentence states the core purpose, followed by return details, search scope, and parameter/return documentation. Every sentence earns its place with no redundant information, making it efficient and easy to parse.

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 (search operation with one parameter), rich annotations covering safety and behavior, and the presence of an output schema (described in the Returns section), the description is complete. It explains what the tool does, what it returns, where it searches, and provides parameter examples, leaving no significant gaps for agent understanding.

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 0%, but the description provides the 'Args' section that explains the single parameter 'query' as 'topic to search' and gives examples ('VAT digital services', 'R&D tax relief SME'). This adds meaningful semantic context beyond the schema's technical constraints (string with length limits), though it doesn't fully compensate for the lack of 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 specific action ('Search GOV.UK for HMRC tax guidance documents') and resource ('HMRC tax guidance documents'), distinguishing it from sibling tools like 'hmrc_check_mtd_status' or 'hmrc_get_vat_rate' which perform different HMRC-related functions. It precisely defines the scope as searching official GOV.UK content filtered to HMRC publications.

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 context by specifying it searches for 'HMRC tax guidance documents' on GOV.UK, suggesting it should be used when looking for official tax guidance rather than other HMRC data. However, it doesn't explicitly state when to use this vs. alternatives like 'legislation_search' or provide clear exclusions for when other tools might be more appropriate.

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

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

The description adds valuable behavioral context beyond annotations: it warns about territorial extent limitations ('may apply to England & Wales but not Scotland or Northern Ireland') and clarifies what information is returned. While annotations cover safety (readOnlyHint, idempotentHint), the description provides domain-specific behavioral insights that annotations don't capture.

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 perfectly structured: purpose statement first, key return values listed, important usage warning highlighted, and parameter/return format clearly specified. Every sentence adds value with zero redundancy, making it easy for an agent to parse quickly.

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 (legislation retrieval with territorial considerations), the description provides complete context: purpose, return values, important caveats, parameter structure, and return format. With annotations covering safety and an output schema presumably detailing the JSON structure, this description gives the agent everything needed to use the tool correctly.

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

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

With 0% schema description coverage, the description carries full burden for parameter semantics. It provides the structure (params object with type, year, number, section) and clarifies the return format. While it doesn't detail each parameter's purpose, it gives enough context for the agent to understand what's needed, compensating reasonably for the schema gap.

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 specific action ('Retrieve a specific section') and resource ('UK Act or Statutory Instrument'), distinguishing it from sibling tools like legislation_search or legislation_get_toc. It precisely defines what the tool does beyond just restating the name.

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

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

The description provides clear context about when to use this tool ('Retrieve a specific section') and includes an important usage note about checking territorial extent. However, it doesn't explicitly contrast with alternatives like legislation_search or legislation_get_toc, which would be needed for a perfect 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 provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering safety and idempotency. The description adds valuable context about the return format ('JSON array of strings in format section-N: Title text') and the relationship with legislation_get_section, which enhances behavioral understanding beyond annotations.

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

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

The description is efficiently structured with clear sections: purpose, return format, usage note for legislation_get_section, parameters, and return type. Every sentence adds value without redundancy, and key information is front-loaded.

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

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

Given the tool's moderate complexity, rich annotations, and the presence of an output schema, the description provides complete context. It covers purpose, usage guidelines, parameter semantics, and output format, making it fully adequate for an AI agent to understand and invoke the tool correctly.

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

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

Schema description coverage is 0%, but the description compensates by explaining the params object structure (type, year, number) and providing examples of type values ('ukpga', 'uksi', etc.). However, it doesn't fully document all parameter details like year range or number constraints, leaving some gaps.

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 specific action ('Retrieve the table of contents'), resource ('for a UK Act or SI'), and output format ('structural elements with XML id and title'). It distinguishes from sibling tools like legislation_get_section by focusing on the table of contents rather than individual sections.

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

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

The description provides explicit guidance on when to use this tool vs alternatives: it specifies to use legislation_get_section for retrieving specific sections, and clarifies the parameter format difference ('use 47, not section-47'). It also references legislation_search for obtaining the type parameter value.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds valuable context beyond annotations: it specifies the source (legislation.gov.uk), describes the ranking of results, and outlines the return format (JSON with specific fields and total count).

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: first sentence states purpose, second describes returns, third gives usage guidelines, and fourth outlines parameters and return format. Every sentence adds value with zero 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's moderate complexity, rich annotations (readOnlyHint, openWorldHint, idempotentHint), and the presence of an output schema (implied by 'Returns: str: JSON...'), the description is complete. It covers purpose, usage, parameters, and return format adequately without needing to duplicate structured data.

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 0%, so the description must compensate. It provides the 'params' object with query, optional type filter, and optional year, which matches the input schema. While it doesn't detail enum values for 'type' or constraints for 'year' and 'query', it gives enough semantic context for basic usage.

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

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

The description clearly states the tool searches UK legislation on legislation.gov.uk, specifying the exact resource (UK legislation) and action (search). It distinguishes from siblings like 'legislation_get_toc' and 'legislation_get_section' by explaining that those are for exploring structure and provisions after searching.

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

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

The description provides explicit guidance on when to use this tool vs alternatives: 'Use legislation_get_toc to explore structure, then legislation_get_section for provisions.' This clearly differentiates it from sibling tools and establishes a workflow.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds valuable context beyond this: it specifies the return format (JSON array of MemberResult objects with specific fields like id, name, party), mentions it handles both current and former members, and implies partial name matching. However, it doesn't detail rate limits, auth needs, or pagination behavior, keeping it from a perfect score.

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 core purpose in the first sentence, followed by return details and usage guidelines. Every sentence earns its place: the first defines the tool, the second specifies returns, the third provides integration guidance, and the last details parameters and output. No wasted words, and it's appropriately sized for a simple lookup tool.

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

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

Given the tool's low complexity (1 parameter), rich annotations (covering read-only, open-world, idempotent), and the presence of an output schema (implied by the Returns section), the description is complete enough. It explains what the tool does, when to use it, parameter semantics, and output structure, leaving no gaps for an AI agent to understand and invoke it correctly in context with siblings.

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 0%, so the description must compensate for parameter documentation. It adds meaning by explaining that the 'name' parameter accepts 'full or partial member name' and provides examples ('Starmer', 'Baroness Hale'), which clarifies usage beyond the schema's basic type constraints. However, it doesn't cover edge cases like minimum characters or formatting, and with only one parameter, the baseline is high but not fully comprehensive.

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 ('Search for') and resource ('current or former MP or Lord by name'), making the purpose specific. It distinguishes from siblings like parliament_member_debates by focusing on member lookup rather than debates, and from parliament_member_interests by not handling interests. The mention of 'current or former' adds nuance beyond just 'find member'.

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

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

The description provides explicit guidance on when to use this tool: for searching MPs/Lords by name. It also specifies an alternative use case by stating 'Use the integer member_id with parliament_member_debates', indicating this tool is for initial lookup and another tool (parliament_member_debates) should be used for subsequent actions with the ID. This clearly differentiates it from siblings like parliament_search_hansard or votes_search_divisions.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds useful context: it clarifies that the topic filter is an 'exact phrase' search (implied in schema but emphasized here) and mentions the prerequisite of using parliament_find_member. However, it doesn't disclose additional behavioral traits like rate limits, pagination, or error handling beyond what annotations cover.

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

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

The description is well-structured and concise: the first sentence states the purpose, the second provides usage guidance, and the Args/Returns sections are clearly formatted. Every sentence earns its place—no wasted words—and key information is front-loaded. The formatting with bullet-like sections enhances readability without verbosity.

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

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

Given the tool's moderate complexity (1 required parameter, optional filtering), rich annotations (covering safety and idempotency), and the presence of an output schema (Returns specifies JSON array of HansardContribution objects), the description is complete enough. It covers purpose, prerequisites, parameter semantics, and return format, addressing gaps from the 0% schema coverage without redundancy.

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 0%, so the description must compensate. It adds meaningful semantics: it explains that member_id is an 'integer member ID' obtained from parliament_find_member (prerequisite context) and that topic is an 'optional phrase to filter by topic' with examples ('housing benefit', 'net zero'). This clarifies parameter purposes beyond the bare schema, though it doesn't detail all schema constraints (e.g., minimum value for member_id).

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: 'Retrieve Hansard contributions by a specific member, optionally filtered by topic.' It specifies the verb ('retrieve'), resource ('Hansard contributions'), and scope ('by a specific member'), distinguishing it from siblings like parliament_search_hansard (general search) or parliament_member_interests (different resource).

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

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

The description provides explicit usage guidance: 'Use parliament_find_member first to obtain the integer member ID.' This clearly indicates a prerequisite and distinguishes it from alternatives like parliament_search_hansard (which likely doesn't require a member ID). It also mentions optional topic filtering, setting expectations for when to use this feature.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds valuable context beyond this: it specifies the data source ('registered financial interests'), lists the categories of interests returned, and mentions the JSON return format. However, it doesn't detail rate limits, authentication needs, or pagination behavior.

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

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

The description is front-loaded with the core purpose, followed by usage guidance, return details, and parameter explanations in a structured 'Args' and 'Returns' section. Every sentence adds value without redundancy, making it efficient and well-organized.

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 (1 required parameter, optional filter), rich annotations, and the presence of an output schema (which handles return values), the description is complete. It covers purpose, prerequisites, parameter semantics, and return format, leaving no gaps for the agent to infer critical usage details.

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

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

With 0% schema description coverage, the description fully compensates by explaining both parameters. It clarifies that member_id is an 'integer member ID' obtained from parliament_find_member, and it lists examples of category filters (e.g., 'employment', 'donations', 'land') and states that omitting it returns all categories. This adds essential meaning not present in the schema.

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

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

The description clearly states the specific action ('Look up registered financial interests') and resource ('for a member of Parliament'), distinguishing it from sibling tools like parliament_find_member (which finds members) or parliament_member_debates (which gets debates). It explicitly lists the categories of interests returned, making the purpose highly specific.

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

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

The description provides explicit guidance on when to use this tool: 'Use parliament_find_member first to obtain the integer member ID.' This directly addresses the prerequisite and distinguishes it from alternatives by specifying the required input source. It also mentions the optional category filter for focused queries.

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

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

The description adds valuable behavioral context beyond annotations: it specifies the return format (JSON array with specific fields), mentions the types of content returned (debates, questions, speeches), and provides usage context. Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior, so the description appropriately supplements rather than contradicts.

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: first sentence states purpose, second describes returns, third provides usage context, then clearly labeled Args and Returns sections. Every sentence adds value with zero 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's complexity (search with multiple filters), the description provides complete context: purpose, usage guidelines, parameter semantics, and return format. With annotations covering safety/behavioral traits and the description detailing inputs/outputs, this is comprehensive for a search 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?

With 0% schema description coverage, the description carries full burden for parameter documentation. It clearly explains the 'params' input structure, mentions query, optional date range, and optional member filter, and the Returns section details the output format with specific fields. This fully compensates for the schema coverage gap.

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

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

The description clearly states the tool searches Hansard for parliamentary debates, questions, and speeches, specifying it returns contributions from MPs and Lords with specific fields. It distinguishes from siblings like 'parliament_find_member' or 'parliament_member_debates' by focusing on content search rather than member-specific operations.

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

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

The description provides clear context for when to use this tool ('useful for understanding legislative intent or political context'), but does not explicitly state when not to use it or name specific alternatives among siblings. It implies usage for content-based searches rather than member-focused queries.

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

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds valuable context by specifying what data is returned ('petition title, state, signature count, and dates for government response or parliamentary debate if applicable') and the return format ('JSON array of PetitionSummary objects'), which goes beyond the annotations. No contradictions with annotations exist.

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 core purpose in the first sentence, followed by return details and parameter/return specifications in a structured format. Every sentence adds value without redundancy, making it efficient and easy to parse for an AI agent.

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, rich annotations (covering safety and behavior), and the presence of an output schema (implied by 'Returns: str: JSON array of PetitionSummary objects'), the description is complete. It explains the purpose, return data, and parameters adequately, with no significant gaps for a search tool.

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

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

Schema description coverage is 0%, but the input schema includes detailed descriptions for 'query' and 'state' parameters. The description mentions 'query and optional state filter' in the Args section, adding minimal semantics beyond the schema. With one parameter (a nested object) and schema doing the heavy lifting, this meets the baseline for adequate parameter information.

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

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

The description clearly states the specific action ('Search UK Parliament petitions by keyword') and resource ('UK Parliament petitions'), distinguishing it from sibling tools like 'parliament_search_hansard' or 'parliament_find_member'. It provides a precise verb+resource combination that leaves 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 description implies usage through the phrase 'Search UK Parliament petitions by keyword', suggesting this is for keyword-based searches of petitions. However, it doesn't explicitly state when to use this tool versus alternatives like 'bills_search_bills' or 'legislation_search', nor does it provide exclusions or specific scenarios where this tool is preferred over others.

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

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

The description adds valuable behavioral context beyond annotations: it explains the two-stage process (search then LLM analysis), the graceful degradation when sampling is unavailable, and what gets returned in each case. Annotations cover safety (readOnlyHint=true, destructiveHint=false) and data characteristics (openWorldHint=true), but the description adds implementation details that help the agent understand tool behavior.

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

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

The description is well-structured and efficiently written. The first sentence states the core purpose, followed by implementation details, fallback behavior, and clear sections for Args and Returns. Every sentence adds value with no redundancy or wasted words.

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

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

Given the tool's complexity (search + LLM analysis), the description provides complete context. It explains the process, fallback behavior, parameter usage, and return format. With an output schema present, the description doesn't need to detail return values, and it adequately compensates for the lack of schema descriptions through clear parameter explanations.

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

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

The description provides essential parameter semantics despite 0% schema description coverage. It explains that 'policy_text' is a 'full description' of the proposal to assess, and 'topic' is used as 'search keyword' for Hansard. The Args section clarifies the parameter structure (PolicyVibeInput containing both fields), adding significant value beyond the bare schema.

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

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

The description clearly states the tool's purpose: 'Assess the likely parliamentary reception of a policy proposal' with specific verbs ('searches Hansard', 'uses LLM sampling', 'classify sentiment', 'extract supporters/opponents/concerns'). It distinguishes from siblings like 'parliament_search_hansard' by adding analysis beyond simple 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?

The description provides clear context for when to use this tool: for assessing parliamentary reception of policy proposals. It doesn't explicitly state when NOT to use it or name alternatives, but the purpose naturally differentiates it from sibling tools like 'parliament_search_hansard' (which only searches) or 'bills_search_bills' (which deals with bills rather than policy proposals).

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

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

Annotations already indicate read-only, non-destructive, idempotent, and open-world operations. The description adds valuable behavioral context beyond annotations: it discloses response truncation limits ('truncated to 100 per side'), response constraints ('to fit response limits'), and data accuracy guarantees ('Total voter counts are always accurate regardless of truncation').

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 the core purpose, followed by behavioral details, then parameter and return sections. Every sentence adds value: the first states the purpose, the next two explain truncation behavior, and the last two document inputs/outputs without redundancy.

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

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

Given the tool's moderate complexity, rich annotations, and presence of an output schema, the description is reasonably complete. It covers purpose, behavioral constraints, and basic I/O structure. The output schema handles return values, so the description doesn't need to detail them. Minor gaps remain in parameter documentation.

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 0%, but the description provides minimal parameter guidance in the 'Args' section, naming 'division_id and house' and referencing the input type. However, it doesn't add meaningful semantics beyond what's implied by the schema structure, leaving parameters largely undocumented in both schema and description.

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

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

The description clearly states the verb ('Get full detail') and resource ('parliamentary division'), specifying it includes 'how each member voted'. It distinguishes from sibling 'votes_search_divisions' by focusing on detailed results for a specific division rather than searching.

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 context by referencing 'division_id from votes_search_divisions results', suggesting this tool follows a search. However, it doesn't explicitly state when to use this vs alternatives or provide exclusions, though the distinction from 'votes_search_divisions' is clear.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds useful context about what data is returned (summaries including title, date, vote counts, pass status) and the relationship to the sibling tool, but doesn't mention rate limits, authentication needs, or pagination behavior.

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

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

The description is perfectly structured: first sentence states purpose, second describes returns, third provides sibling guidance, then separate Args and Returns sections. Every sentence earns its place with no wasted words, and key information is front-loaded.

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

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

Given the tool has comprehensive annotations (readOnly, openWorld, idempotent, non-destructive), an output schema exists (so return values are documented), and the description provides clear purpose, usage guidelines, and parameter overview, this is complete for a search tool. The description effectively complements the structured data without redundancy.

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 0%, but the description provides a helpful overview: 'optional query, house, date range, member filter.' It explains the purpose of the single 'params' parameter and its nested structure, though it doesn't detail individual sub-parameters like query format or date ranges. This adds meaningful context beyond the bare 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 searches parliamentary divisions (votes) in Commons or Lords, specifying the verb 'search' and resource 'parliamentary divisions'. It distinguishes from sibling 'votes_get_division' by indicating this returns summaries while the sibling provides 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?

The description explicitly provides when-to-use guidance: 'Use votes_get_division with the division ID for full voter lists.' This clearly distinguishes between this summary search tool and the detailed division tool, helping the agent choose the right alternative.

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