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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly describes the tool's behavior: it returns today's birthdays only (not historical or future dates), outputs a JSON array with specific fields (ID, name, party, etc.), and has no parameters. However, it doesn't mention potential limitations like 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 well-structured and front-loaded with the core purpose, followed by usage guidelines and alternatives. Every sentence adds value: the first explains what the tool does, the second describes the output format, the third provides usage scenarios, the fourth explains the lack of parameters, and the last two offer sibling tool alternatives.

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 (0 parameters, no output schema, no annotations), the description is largely complete. It covers purpose, output format, usage guidelines, and alternatives. However, without annotations or output schema, it could benefit from more detail on behavioral aspects like error handling or data freshness.

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

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

The input schema has 0 parameters with 100% coverage, so the baseline is 4. The description adds value by explicitly stating 'This tool takes no parameters as it always returns today's birthdays,' which clarifies why there are no parameters and reinforces the tool's fixed scope.

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 ('Lists all Members of Parliament celebrating their birthday today') and the resource ('Members of Parliament'), distinguishing it from siblings like 'get_overview' or 'list_persons' by focusing exclusively on today's birthdays. It provides concrete details about what information is included (names, political parties, birth dates).

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 ('when a user specifically asks about birthdays, wants to know which MPs are celebrating today, or needs to create 'on this day' content') and provides clear alternatives ('use the 'get_overview' tool instead' for general overview, and 'use the 'get_photo' tool' for photos). It effectively guides the agent on tool selection.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool retrieves information (implying read-only, non-destructive behavior) and specifies the scope of data returned. However, it lacks details on error handling, rate limits, or authentication needs, leaving behavioral gaps for a tool with no 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?

Two sentences that are front-loaded with the core purpose, followed by usage guidance. Every phrase adds value without redundancy, making it efficiently structured and 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 tool's low complexity (1 parameter, no output schema, no annotations), the description is mostly complete—it covers purpose, usage, and data scope. However, without annotations or output schema, it could benefit from more behavioral details (e.g., response format), slightly reducing completeness.

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

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

Schema description coverage is 100%, with the parameter 'committeeId' well-documented in the schema. The description adds context by implying this ID is for a 'specific parliamentary committee,' reinforcing its purpose without repeating schema details. With only one parameter, this minimal addition is sufficient for a high score.

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 ('Retrieves') and resource ('detailed information about a specific parliamentary committee'), specifying what information is included (members, recent activities, description, composition, leadership roles, recent work). It distinguishes from sibling tools like 'get_committees' by focusing on details for a specific committee rather than listing committees.

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

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

Explicitly states 'Use this when you need comprehensive information about a particular committee's structure and activities,' providing clear context for when to use this tool. It implies alternatives like 'get_committees' for broader lists, though not explicitly named, the specificity suffices for high 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?

With no annotations, the description carries full burden and does well: it discloses the response format (JSON array), scope (all active committees), and that it takes no parameters. However, it lacks details on potential limitations like pagination, rate limits, or error handling, which would be useful for a read operation.

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

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

Front-loaded with the core purpose, followed by usage guidelines and workflow. Sentences are efficient, but it could be slightly more concise by integrating some details (e.g., merging policy area examples into one phrase). Overall, well-structured with minimal 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 0 parameters, no annotations, and no output schema, the description is largely complete: it explains purpose, usage, response format, and sibling relationship. However, it doesn't specify if the list is filtered (e.g., only active committees) or mention any authentication needs, leaving minor gaps for a read tool.

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

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

The schema has 0 parameters with 100% coverage, so the baseline is 4. The description adds value by explicitly stating 'takes no parameters as it returns all active committees,' clarifying the absence of inputs and reinforcing the tool's behavior, which compensates for any minimal 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 verb ('retrieves') and resource ('parliamentary committees'), specifying what data is returned (IDs, names, URLs) and the format (JSON array). It distinguishes from sibling 'get_committee_details' by emphasizing this lists all committees without filtering, making the purpose specific and differentiated.

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

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

Explicitly states when to use: when users ask about committees, want to know which exist, or need committees by policy areas. It provides a clear alternative ('get_committee_details' for detailed info) and explains the workflow (use this first, then details tool), offering comprehensive guidance on usage versus siblings.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: content extraction from PDF/DOCX, potential truncation for long documents, pagination mechanism with detailed response fields, and the iterative calling pattern needed for complete retrieval. It doesn't mention rate limits or authentication needs, but covers the core operational behavior well.

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

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

The description is appropriately sized and front-loaded with the core purpose. Every sentence adds value: the first states the purpose, the second explains content extraction, the third warns about truncation, and the rest provide essential pagination details and usage guidelines. While somewhat detailed, all information is necessary for this complex 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 complexity (pagination, content extraction) and lack of both annotations and output schema, the description does an excellent job of completeness. It explains the truncation behavior, describes the response structure (isTruncated, totalLength, etc.), provides a step-by-step usage example, and clarifies when to use the tool. The main gap is no explicit mention of error conditions or rate limits.

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 significant value beyond the schema by explaining the pagination workflow: it clarifies how the 'offset' parameter interacts with the response fields (nextOffset), provides a concrete usage example with multiple calls, and explains the default behavior (offset=0). This contextual information helps the agent understand parameter usage in practice.

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 ('downloads', 'extracts text content') and identifies the resource ('parliamentary document'). It distinguishes itself from sibling tools like 'get_document_details' (which likely provides metadata) by emphasizing content extraction for analysis rather than just 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 explicitly states when to use this tool ('when you need to analyze or discuss the specific content of a document rather than just its metadata') and provides a clear alternative (implied metadata tools like 'get_document_details'). It also includes detailed pagination guidance for handling long documents.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes what the tool returns (metadata without content, specific fields like title/type/number/dates/version/links) and clarifies the read-only nature (retrieves, not downloads). It could mention potential limitations like rate limits or authentication needs, but covers core behavior well.

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 three sentences: the first states purpose and output, the second details returned information, and the third provides usage guidance. Every sentence adds value without redundancy, making it easy to parse and front-loaded with key information.

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

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

For a single-parameter read operation with no output schema, the description provides comprehensive context: what it does, what it returns, when to use it, and alternatives. It could benefit from mentioning the response structure more explicitly since there's no output schema, but it covers the essential information well given the tool's complexity.

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

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

The schema description coverage is 100%, with the single parameter 'nummer' well-documented in the schema as 'Document number (e.g., '2024D39058') - the unique identifier'. The description doesn't add parameter-specific information beyond what's in the schema, so it meets the baseline for high schema coverage.

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

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

The description clearly states the specific action ('retrieves metadata'), resource ('parliamentary document'), and output format ('structured JSON format'). It explicitly distinguishes this tool from its sibling 'download_document' by specifying it does not download actual content, making the purpose unambiguous and well-differentiated.

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

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

The description provides explicit guidance on when to use this tool ('ideal for getting quick information about a document and obtaining the relevant links') and when not to use it ('To actually download the document content, use the 'download_document' tool instead'). This clear alternative recommendation helps the agent choose correctly between similar 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool converts URLs and returns formatted links, but lacks details on error handling, rate limits, authentication needs, or what 'properly formatted' entails. For a tool with no annotations, this is insufficient behavioral context.

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

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

The description is concise and front-loaded, with three sentences that each add value: the core function, input specifics, and usage context. There is no wasted text, and it efficiently communicates essential information.

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

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

Given no annotations, no output schema, and 2 parameters with full schema coverage, the description is adequate but has gaps. It explains the tool's purpose and usage context well, but lacks details on behavioral traits (e.g., error handling) and return values. For a simple conversion tool, it's minimally viable but could be more 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 schema already documents both parameters (pdfUrl, tkUrl) with clear descriptions. The description adds marginal value by mentioning the types of links accepted ('direct PDF link or a Tweede Kamer webpage link'), but doesn't provide additional syntax or format details beyond the schema. Baseline 3 is appropriate when 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 purpose with specific verbs ('converts', 'returns') and resources ('document URLs', 'clickable links'). It distinguishes from siblings by mentioning a specific workflow ('use this after get_document_details'), making its role in the toolset explicit.

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

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

The description provides clear context on when to use the tool ('after get_document_details') and what inputs it accepts ('direct PDF link or a Tweede Kamer webpage link'). However, it doesn't explicitly state when not to use it or name alternatives among siblings, though the workflow hint implies differentiation.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior: pagination mechanics (10 documents per page, hasMoreDocuments field), response structure (two main sections), and the iterative usage pattern. It doesn't mention rate limits or authentication requirements, but covers the core operational behavior well.

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 comprehensive but somewhat verbose. While all information is relevant, it could be more front-loaded with the core purpose. The explanation of pagination mechanics and sibling tool relationships, while valuable, extends the description length. Every sentence earns its place, but the structure could be tighter.

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

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

Given the tool's complexity (pagination, multiple data sections, iterative usage) and lack of annotations/output schema, the description does an excellent job of providing context. It explains the response structure, pagination behavior, and workflow. The main gap is the absence of output schema details, but the description compensates well by describing the response format and 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 schema description coverage is 100%, so the baseline is 3. The description adds significant value by explaining the pagination context ('first call with page=1, then check...'), the relationship between the page parameter and document retrieval, and the iterative scrolling workflow. This provides practical usage semantics beyond the schema's basic parameter documentation.

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 provides a comprehensive overview of recent parliamentary activities with two specific sections (recent documents and MP birthdays). It distinguishes itself from siblings by being the 'ideal starting point' and explicitly mentions alternative tools like get_document_details and search_tk for follow-up actions.

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 ('first when a user asks for general information about recent parliamentary activities or needs a starting point for research') and when to use alternatives ('After getting this overview, you can use other tools like...'). It also explains the iterative pagination workflow for scrolling through documents.

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?

No annotations are provided, so the description carries the full burden. It discloses that the tool returns a binary resource for display or saving, which is useful behavioral context. However, it lacks details on potential errors (e.g., if no photo exists), rate limits, or authentication needs, leaving gaps for a read operation.

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 usage guidance. Every sentence earns its place by adding value—no redundant or vague language. It's efficiently structured and 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 tool's low complexity (1 parameter, no output schema, no annotations), the description is mostly complete. It covers purpose, usage, and output format. However, without annotations or output schema, it could benefit from more behavioral details (e.g., error handling), but it's adequate for a simple retrieval tool.

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

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

Schema description coverage is 100%, with the parameter 'personId' fully documented in the schema as 'MP's numeric ID - the unique identifier for the Member of Parliament whose photo you want to retrieve.' The description adds no additional parameter information beyond this, so it meets the baseline for high schema coverage without compensating further.

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 ('Retrieves'), resource ('official portrait photograph of a Member of Parliament'), and output format ('binary resource'). It distinguishes this tool from siblings like 'list_persons' (which lists MPs) or 'get_document_content' (which retrieves documents), 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?

It explicitly states when to use this tool: 'when you need to include a visual representation of an MP in reports, presentations, or profiles.' This provides clear context for usage, helping the agent choose this over alternatives like textual data tools. No exclusions are mentioned, but the guidance is sufficient for decision-making.

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?

No annotations are provided, so the description carries the full burden. It discloses key behavioral traits: the response format (structured JSON with chronological and grouped lists), sorting (by date, most imminent first), and an optional parameter for limiting results. However, it lacks details on error handling, rate limits, or authentication needs, which are important for a tool with no annotations.

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

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

The description is appropriately sized and front-loaded, starting with the core purpose and response details. Every sentence adds value, such as usage guidelines and sorting behavior, but it could be slightly more concise by integrating some details more tightly 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 no annotations and no output schema, the description does a decent job covering purpose, usage, and basic behavior. However, it lacks information on error cases, pagination, or the exact structure of the JSON response, which would be helpful for an agent to handle the tool effectively in more complex scenarios.

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

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

The input schema has 100% description coverage, with the 'limit' parameter documented as 'Maximum number of activities to return (default: 20, max: 100)'. The description adds value by explaining the purpose of limiting results ('You can limit the number of results using the optional 'limit' parameter') and implying its optionality, but doesn't provide additional semantics beyond what the schema already covers.

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 ('Retrieves') and resource ('list of upcoming parliamentary activities'), specifying the types (debates, committee meetings, other events) and distinguishing it from siblings like get_committee_details or get_voting_results by focusing on upcoming activities rather than details of specific entities.

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 states when to use this tool: 'when a user asks about the parliamentary agenda, wants to know what events are coming up, or needs information about specific types of parliamentary activities.' It also provides context on usefulness for planning or overview, though it doesn't explicitly name alternatives, the guidance is clear 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?

No annotations are provided, so the description carries the full burden. It discloses that the response is a structured JSON object sorted by date and includes detailed information like vote counts and party alignments, but it lacks details on permissions, rate limits, or error handling. For a read operation with no annotations, this is adequate but not comprehensive.

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

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

The description is front-loaded with purpose and usage, but it includes verbose sentences like 'This tool is particularly valuable for tracking political alignments...' that add minimal operational value. It could be more concise by focusing on essential details without the explanatory 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 no annotations, 100% schema coverage, and no output schema, the description adequately covers purpose, usage, and basic behavioral traits. However, it lacks details on response structure (e.g., JSON fields) and error cases, which would improve completeness for a tool with no output schema.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (format and limit) thoroughly. The description adds minor context by explaining that 'summary' format provides a more structured representation with renamed fields, but this largely repeats schema information. Baseline 3 is appropriate when 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 verb 'retrieves' and the resource 'recent voting results on parliamentary motions and bills,' distinguishing it from siblings like get_committee_details or list_persons by focusing on voting outcomes rather than committees, documents, or persons.

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 states when to use this tool: 'when a user asks about recent parliamentary votes, wants to know how parties voted on specific issues, or needs to analyze voting patterns.' This provides clear context and distinguishes it from alternatives like search_tk or get_overview.

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?

No annotations are provided, so the description carries the full burden. It discloses key behavioral traits: the tool returns a complete directory (implying no pagination or limits), specifies the output format ('JSON array'), and mentions use cases like creating reports or finding IDs for other tools. However, it doesn't address potential rate limits, authentication needs, or data freshness, leaving some gaps for a tool with no 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 front-loaded: the first sentence states the core purpose, followed by usage guidelines and alternatives. Every sentence adds value—explaining output format, use cases, parameter absence, and sibling tool differentiation—with no redundant information. It efficiently covers all necessary aspects in a compact form.

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 (0 parameters, no output schema, no annotations), the description is mostly complete: it covers purpose, usage, output format, and parameter semantics. However, without annotations or an output schema, it could benefit from more detail on behavioral aspects like error handling or data updates. It adequately compensates for the lack of structured data but has minor gaps.

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

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

The tool has 0 parameters, and schema description coverage is 100% (empty schema). The description adds value by explicitly stating 'This tool takes no parameters as it returns all current MPs,' which clarifies the absence of inputs beyond what the schema indicates. Since there are no parameters, a baseline of 4 is appropriate, and the description reinforces this clearly.

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: 'Provides a complete directory of current Members of Parliament with their IDs, names, titles, party affiliations, and faction memberships.' It specifies the verb ('Provides'), resource ('directory of current Members of Parliament'), and output format ('JSON array'), and distinguishes it from sibling tools like 'search_tk' by emphasizing it returns all MPs without filtering.

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: 'when a user needs comprehensive information about all MPs, wants to analyze the composition of parliament by party, or needs to find specific MPs by name or party.' It also provides clear alternatives: 'For a more targeted approach when looking for specific MPs, consider using the 'search_tk' tool with the MP's name.' This includes both usage scenarios and 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: the response format ('structured JSON object with paginated results and metadata'), sorting behavior ('sorted by date with the most recent documents first'), and search syntax details. It doesn't mention rate limits or authentication requirements, but covers most operational aspects well.

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

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

The description is appropriately sized and front-loaded with the core purpose in the first sentence. Each subsequent sentence adds valuable information about usage, parameters, search syntax, and sorting. While comprehensive, it maintains good flow without unnecessary repetition, though it could be slightly more concise in the syntax explanation 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 (search with advanced syntax, pagination, filtering) and no output schema, the description provides substantial context: response format, sorting behavior, parameter usage, and search syntax. With no annotations, it adequately covers operational aspects, though it doesn't specify error conditions or exact response structure details that an output schema would 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?

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds some value by explaining the 'category' parameter options with examples and detailing the 'query' parameter's advanced syntax, but doesn't add significant meaning beyond what the schema provides. The baseline of 3 is appropriate given the comprehensive schema documentation.

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: 'Performs a search specifically for documents of a certain category' with specific examples (questions, motions, letters). It distinguishes from siblings by mentioning 'more targeted search results than the general search provides' and lists sibling tools like 'search_tk' and 'search_tk_filtered' that likely provide broader searches.

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: 'when a user wants to find documents of a specific type that match certain keywords' and 'when they need more targeted search results than the general search provides.' It distinguishes from alternatives by contrasting with 'general search' and the sibling tools suggest broader search capabilities.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by explaining search syntax behavior (AND semantics by default, exact phrases with quotes, NOT/OR/NEAR operators), but doesn't mention pagination behavior, rate limits, authentication requirements, or what happens with empty results. It provides good operational context but misses some important behavioral aspects.

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

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

The description is appropriately sized and front-loaded with the core purpose. The first sentence establishes what the tool does, followed by usage guidance, then detailed syntax examples. While comprehensive, some syntax details could be more concise, but overall structure is logical 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?

For a search tool with 4 parameters, 100% schema coverage, but no annotations or output schema, the description provides good context. It explains the tool's scope, when to use it, and detailed search syntax. However, without an output schema, it doesn't describe what results look like or their structure, leaving some gaps in completeness.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds some value by explaining query syntax examples and operators, but doesn't provide additional meaning for format, limit, or page parameters beyond what the schema already states. 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 performs a 'comprehensive search across all parliamentary data including documents, activities, and cases' with specific resources listed. It distinguishes from sibling tools by mentioning 'general searches' and 'regardless of document type or context', differentiating it from more specific tools like search_by_category or search_tk_filtered.

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 usage guidance: 'Use this for general searches when you need information on any topic discussed in parliament, regardless of document type or context.' This clearly indicates when to use this tool versus more specialized alternatives, providing excellent context for tool selection.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes search syntax rules (quotes, NOT, OR, NEAR operators), which are critical behavioral traits not covered by the schema. However, it doesn't mention pagination behavior, rate limits, or authentication requirements, leaving some gaps.

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 purpose and usage guidelines, then provides detailed search syntax. While comprehensive, some syntax examples could be more concise, but overall it earns its place with valuable information.

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

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

For a search tool with no annotations and no output schema, the description provides good context about behavior and usage. It covers search syntax thoroughly and distinguishes from siblings. The main gap is lack of information about return format or result structure, which would be helpful given no output schema exists.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema - it mentions 'category filter' for the 'type' parameter but doesn't provide additional semantic context. The baseline of 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 'performs a targeted search within a specific category of parliamentary data' and distinguishes it from the general search by allowing limitation to documents, activities, or cases. It explicitly mentions the sibling tool 'search_tk' (general search) in the first sentence, providing 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: 'Use this when you need more focused search results within a particular content type.' It contrasts with the general search tool and specifies the appropriate context for usage, making it clear when to choose this over alternatives.

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