ckan_buscar

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

With no annotations, the description carries the burden; it does disclose the shape of returned items (id, format, datastore presence, download URL), which signals a read-only listing. It says nothing about pagination via limite, error behavior for unknown portals, or whether network access to arbitrary portal URLs is permitted.

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 compact sentences, with the return payload listed up front and portal values second. Slightly telegraphic phrasing ('portal: ...') but no wasted sentences.

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?

There is no output schema, and the description usefully enumerates the returned fields, which covers the return-value gap. But for a 3-parameter search tool with zero schema coverage, the missing explanation of the required 'texto' and the 'limite' default is a real omission.

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 does well on 'portal' by enumerating valid values (substituting for a missing enum) and the /api/3/action URL form, but 'texto' and 'limite' are never explained – texto is required yet its search semantics are undefined.

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?

Names the resource (CKAN portal datasets plus their resources) and enumerates the fields returned, so an agent knows this is a discovery/search call. It does not explicitly contrast with the sibling ckan_filas, which presumably fetches dataset rows, leaving the boundary fuzzy.

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?

No statement of when to use this versus ckan_filas, descargar, or socrata_filas. The discovery-then-rows workflow is only inferable from the sibling names, not from the description.

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