Catalunya 2022

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds context about the returned hierarchy and slugs for navigation, which is valuable beyond the annotations.

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

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

The description is a single, front-loaded sentence that efficiently conveys the tool's purpose. The specific numbers (3 spheres, 12 goals) add useful context but could be slightly more concise.

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

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

For a read-only tool with one simple parameter and no output schema, the description is fairly complete. It explains the tool's output and its relationship to get_section.

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

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

Schema coverage is 100% and the schema already describes the locale parameter. The description does not add anything about parameters, so baseline 3 is appropriate.

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

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

The description clearly states the tool gets the complete structure of a specific policy document, mentioning the hierarchy and linking to get_section for navigation. It distinguishes from siblings like get_section (section navigation) and list_proposals (list proposals).

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

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

The description implies usage: to obtain the full document structure and then use get_section for navigation. However, it does not explicitly state when not to use it or provide alternatives beyond get_section.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, covering safety and idempotency. The description adds context about slug patterns and static pages, which is useful beyond annotations, but doesn't mention rate limits or authentication needs. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose, followed by slug patterns and a clear alternative tool mention. Every sentence adds value without waste, 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 low complexity, rich annotations, and full schema coverage, the description is mostly complete. It lacks output schema details, but the purpose and usage are well-covered. A minor gap exists in not explicitly stating return format, but it's adequate for this 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?

Schema description coverage is 100%, so the schema fully documents both parameters. The description adds meaning by explaining slug patterns and static page examples, but this doesn't significantly enhance the schema's details. Baseline 3 is appropriate as the schema carries the burden.

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

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

The description clearly states the action ('Retrieve the full text') and resource ('any section of the Catalunya 2022 document'), specifying it's by canonical slug. It distinguishes from sibling get_document_metadata by mentioning that tool for discovering slugs, 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?

It explicitly states when to use this tool (by canonical slug) and when to use an alternative (get_document_metadata to discover slugs). It also lists static page slugs as examples, providing clear context for usage versus other siblings like list_proposals or search_document.

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 this as a safe, read-only, idempotent operation (readOnlyHint=true, destructiveHint=false, idempotentHint=true). The description adds valuable context beyond annotations by specifying the exact number of items (91), the return fields (actionId, goalId, sphereId, title, slug, url), and the relationship with get_section. No contradiction with annotations.

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

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

The description is efficiently structured in two sentences: the first states purpose and filtering options, the second explains return values and relationship with another tool. Every sentence adds essential information 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 simplicity (list operation with full schema coverage and comprehensive annotations), the description is complete. It covers purpose, usage, return fields, and tool relationships. No output schema exists, but the description adequately specifies return values.

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

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

Schema description coverage is 100%, so the schema fully documents all three parameters. The description adds minimal value beyond the schema by mentioning optional filtering by sphere or goal, but doesn't provide additional syntax or format details. 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 verb ('List') and resource ('all 91 action proposals from the Catalunya 2022 document'), specifying the exact dataset scope. It distinguishes from sibling tools by mentioning get_section for full content, implying this tool provides a summary list rather than detailed content or 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 ('List all 91 action proposals') and when to use an alternative ('Use get_section with the returned slug to read full action content'), providing clear guidance on tool selection. It also mentions optional filtering parameters, indicating usage contexts.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds valuable behavioral details: auto-handling of diacritics and a 10-result limit, which the agent needs to know.

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, no wasted words. Front-loaded with the core action ('Search the Catalunya 2022 - RESET policy document by keyword') followed by key output details and a behavioral note.

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 output schema, the description explains the return structure (up to 10 results, slugs, snippets). It doesn't mention pagination or sorting, but for a focused search tool with a limited result set, this is adequate.

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

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

Schema description coverage is 100%, but the description adds nuance: suggests using locale terms for best results, notes default language, and explains the query parameter's purpose beyond the schema. This additional guidance adds value.

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

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

The description clearly states the tool searches a specific policy document by keyword, returns up to 10 results with slugs and snippets, and handles diacritics. It distinguishes from siblings like get_section (for retrieving a specific section) and list_proposals (for listing proposals).

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 indicates when to use the tool (to find sections in the document) and mentions follow-up with get_section using canonical slugs. It doesn't explicitly say when not to use it, but the sibling context implies alternatives.

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