search_catalog

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that matching is accent-insensitive and that some categories return results that are not yet callable, but it says nothing about authentication, result limits, pagination, or ordering 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?

Two short blocks, front-loaded with the search verb and match scope, followed by the filter semantics. Every clause earns its place; there is no filler or repetition of schema structure.

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?

An output schema exists, so return values need not be explained. The description covers the query semantics and the full category vocabulary, which are the two things an agent needs; only pagination/limit behavior and auth expectations are left unstated.

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% and there are no enums, so the description must compensate — and it largely does: it defines what 'query' matches against and how it is normalized, and enumerates all four valid category literals with their meaning. It does not restate that category is optional/defaults to null, but the schema covers that.

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?

States a specific verb and resource ('Search the government API catalog by keyword') and defines the match surface (name, provider, tags, description), which clearly separates it from the sibling list_apis (unfiltered listing) and describe_api (single-item detail). An agent can pick this tool without opening any schema.

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 category values carry implicit selection guidance ('public' = callable today, 'serpro' = needs contract, 'conecta' = not callable yet), which helps an agent choose a filter. However, there is no explicit statement of when to use this tool versus list_apis, and no exclusions or prerequisites are given.

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