opendata-cat

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

The annotations already provide comprehensive behavioral hints (readOnly, openWorld, idempotent, non-destructive), so the bar is lower. The description adds valuable context about what metadata is returned (fields with types, API endpoint, license, formats, last update) and the workflow relationship with search_datasets, which goes beyond what annotations provide. 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 efficiently structured in two sentences: the first states the purpose and enumerates specific metadata returned, the second provides clear usage guidance. Every element serves a purpose with zero wasted words, making it highly scannable and 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 (single parameter, read-only operation), rich annotations covering safety and behavior, and 100% schema coverage, the description is largely complete. It specifies what metadata is returned and establishes the workflow context. The main gap is the lack of output schema, but the description compensates by listing return elements. A 5 would require explicit mention of response format or error conditions.

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 fully documents the single parameter 'dataset_id' with format examples. The description doesn't add any parameter-specific information beyond what's in the schema, but with complete schema coverage, the baseline score of 3 is appropriate as the schema carries the full 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 specific action ('retorna totes les metadades') and resource ('d'un dataset'), listing concrete metadata elements like fields with types, API endpoint, license, formats, and last update. It explicitly distinguishes from sibling tool 'search_datasets' by stating this should be called after that tool for detailed information on a specific dataset.

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 ('Crida'l després de search_datasets per obtenir detalls complets d'un dataset concret'), clearly positioning it as a follow-up to a sibling tool. It establishes a workflow relationship and specifies the context (after search_datasets for complete details on a specific dataset).

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 return format ('Retorna el total de datasets, recompte per portal i llista de categories amb comptadors') and states 'No requereix paràmetres'. While annotations cover safety and idempotency, the description adds practical usage information about outputs and parameters.

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 concise and front-loaded: three sentences that each serve a distinct purpose (what it does, when to use it, what it returns/requires). There is zero wasted language and the structure flows logically from purpose to usage to implementation details.

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

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

For a zero-parameter read-only tool with comprehensive annotations, the description provides excellent context: it explains the purpose, usage guidelines, and return format. The only minor gap is the lack of output schema, but the description compensates by describing the return values. It's nearly complete for this tool's complexity level.

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 parameters and 100% schema coverage, the baseline would be 4. The description explicitly states 'No requereix paràmetres', which reinforces the empty schema and adds clarity about the tool's parameterless nature.

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 ('Llista totes les categories i temes de datasets disponibles') and resource ('categories i temes de datasets'), and explicitly distinguishes it from sibling tools by mentioning 'abans de fer una cerca amb search_datasets'. It provides a complete picture of what the tool does beyond just 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 explicitly states when to use this tool ('Ideal com a primer pas per descobrir quins tipus de dades hi ha abans de fer una cerca') and names a specific alternative ('search_datasets'). This provides clear guidance on the tool's intended context and when to choose it over 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?

Annotations already provide comprehensive behavioral hints (readOnly, openWorld, idempotent, non-destructive). The description adds valuable context about the tool's role in the workflow (precursor to query_dataset) and what information it returns, which goes beyond what annotations convey. No contradictions with annotations.

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

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

Two concise sentences that are front-loaded with the core purpose and followed by specific usage guidance. Every word serves a clear purpose with zero redundancy or unnecessary elaboration.

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

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

For a simple read-only tool with comprehensive annotations and full schema coverage, the description provides excellent workflow context and purpose clarification. The only minor gap is lack of output format details (no output schema exists), but the description does specify what information will be returned (name, data type, description).

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 100% schema description coverage, the input schema already fully documents the single required parameter dataset_id. The description doesn't add any 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 ('Llista els camps' - lists fields), resource ('d'un dataset'), and output details ('nom, tipus de dada i descripció'). It explicitly distinguishes from sibling tool query_dataset by explaining this should be called first to understand available fields and filters.

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: 'Crida'l abans de query_dataset per saber quins camps i filtres estan disponibles.' This tells the agent exactly when to use this tool (before query_dataset) and why (to understand available fields and filters), creating clear differentiation from 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 cover read-only, open-world, idempotent, and non-destructive traits, but the description adds valuable context by specifying the exact four portals returned and their dataset counts, which goes beyond the annotations. It doesn't contradict annotations and provides operational details not captured in structured fields.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by specific details about the portals and a clear note on parameters. Every sentence adds essential information without redundancy, making it highly 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 (0 parameters, no output schema) and rich annotations, the description is mostly complete. It details the portals and their dataset counts, but since there's no output schema, it could benefit from more explicit information on the return format (e.g., structure of the list).

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 parameters and 100% schema description coverage, the baseline is 4. The description reinforces this by explicitly stating 'No requereix paràmetres,' which adds clarity and confirms the absence of inputs, aligning perfectly with 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 ('Llista els 4 portals de dades obertes catalans') and resource ('portals de dades obertes catalans'), distinguishing it from sibling tools like get_dataset_info or search_datasets which focus on datasets rather than portals. It provides concrete details about the four portals being listed.

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 'No requereix paràmetres,' which provides clear context about when to use this tool (when no parameters are available or needed). However, it doesn't explicitly mention when not to use it or name specific alternatives among the sibling tools for different scenarios.

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 queries go directly to source portals (Socrata SoQL, CKAN datastore, etc.), supports free-text search and pagination, and mentions portal-specific behavior. While annotations cover safety (readOnlyHint: true, destructiveHint: false), the description enriches understanding of how the tool interacts with different data sources.

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 three sentences: states purpose, lists capabilities (filters, search, pagination), and provides usage guidance. Every sentence adds value without redundancy, making it front-loaded and 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?

Given the tool's complexity (5 parameters, nested objects, no output schema) and rich annotations, the description is mostly complete. It covers key behavioral aspects and usage guidance. A slight gap exists in not explicitly describing the return format (though implied as 'files de dades'), but annotations help mitigate this.

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 mentions support for field filters, free-text search, and pagination, which aligns with the schema but doesn't add significant new semantic information beyond what's already in parameter descriptions.

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

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

The description clearly states the tool's purpose: 'Executa una consulta contra un dataset i retorna files de dades reals del portal origen' (execute a query against a dataset and return real data rows from the source portal). It specifies the action (query), resource (dataset), and outcome (return data rows), distinguishing it from siblings like get_dataset_info (metadata) or list_dataset_fields (field listing).

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: 'Crida list_dataset_fields primer per conèixer els camps filtables' (call list_dataset_fields first to know the filterable fields). It also mentions alternative approaches for specific portals (e.g., for Diba and CIDO, use specific filters instead of search), helping differentiate from other query-related 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 strong behavioral hints (readOnly, openWorld, idempotent, non-destructive), so the bar is lower. The description adds useful context about how relationships are calculated ('per similitud temàtica entre portals'), which isn't covered by annotations. However, it doesn't disclose potential limitations like result count, freshness of relationships, or error conditions beyond what annotations imply.

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 concise and front-loaded: the first sentence states the core purpose, the second provides usage context with concrete examples, and the third explains the underlying mechanism. Every sentence earns its place with no wasted words, and the structure moves from general to specific effectively.

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 (cross-portal discovery), rich annotations (covering safety and behavior), and no output schema, the description is reasonably complete. It explains the purpose, usage context, and relationship calculation method. However, it doesn't describe the return format (e.g., list of datasets with metadata) or potential limitations, which would be helpful since there's 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 fully documents the single required parameter (dataset_id). The description doesn't add any parameter-specific information beyond what's in the schema, such as format constraints or example values. With high schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate but doesn't need to.

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 ('retorna', 'descobrir', 'suggerir') and resources ('datasets relacionats d'ALTRES portals'), distinguishing it from siblings like get_dataset_info (single dataset) or search_datasets (search within portals). It explicitly mentions discovering complementary data across different portals, which is unique among the listed tools.

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

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

The description provides clear context for when to use this tool ('ideal per descobrir dades complementàries') with concrete examples (air quality data from Generalitat suggesting traffic data from Barcelona). However, it does not explicitly state when NOT to use it or name specific alternatives among siblings, though the examples imply it's for cross-portal discovery rather than single-portal operations.

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, open-world, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: it covers 7 portals, includes Catalan and Spanish synonyms, and emphasizes the need for multiple searches with different terms for broad topics. 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 three sentences: purpose statement, important usage instruction with example, and behavioral detail about language coverage. Every sentence adds value with zero waste, and key guidance is front-loaded.

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

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

For a search tool with rich annotations (readOnlyHint, openWorldHint, idempotentHint) and full schema coverage, the description provides excellent contextual completeness. It explains the multi-portal scope, language support, and strategic usage advice. The only minor gap is lack of output format details, but with no output schema, this is acceptable.

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 parameters are well-documented in the schema. The description adds minimal parameter semantics beyond the schema, mentioning text search in Catalan/Spanish and covering 7 portals, but doesn't provide additional syntax or format details. Baseline 3 is appropriate given 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 tool's purpose: searching Catalan open data datasets by free text across 7 portals. It specifies the verb 'cerca' (search) and resource 'datasets de dades obertes catalanes', distinguishing it from siblings like get_dataset_info (retrieve specific dataset) or list_categories (list categories).

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

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

Explicit guidance is provided on when and how to use this tool: 'fes múltiples cerques amb termes diferents per cobrir un tema ampli' (do multiple searches with different terms to cover a broad topic), with a concrete example for 'emergències'. It also references sibling tools like list_categories for category filtering.

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