buscar_registros

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

With no annotations provided, the description is responsible for behavioral disclosure. It mentions pagination and ordering but does not state whether the tool is read-only, if it modifies data, or any side effects. There is no indication of authentication requirements, rate limits, or safety profile. For a search tool, read-only behavior is likely but not confirmed.

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 moderately concise but front-loads lengthy prerequisite steps (6 items) with emojis. While the structure is clear, the prerequisites could be condensed, and the observations add useful information. Some sentences are redundant (e.g., item 6 repeats item 4). Overall it is adequate but not streamlined.

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?

The description lacks essential context: no explanation of what data is returned, how results are structured, or how to interpret the output. With 14 parameters and no output schema, the agent needs information about search criteria, filtering behavior, and result format. The prerequisites cover preparatory steps but not the tool's actual output.

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 only indirectly references parameters like 'pagina' and 'ordenar_por' in the observations, but does not explain the purpose or allowed values of the 14 parameters. The prerequisite instructions mention that certain IDs are required, but the description does not link those to specific parameters (e.g., 'contato_id', 'negocio_id'). Most parameters remain undocumented.

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 tool name implies searching records, but the description lacks an explicit statement of purpose such as 'search for records' or 'find registros'. The prerequisites and observations suggest it's used for searching, but the purpose is implied rather than clearly stated. No differentiation from sibling tools like 'buscar_tarefas' is provided.

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 prerequisites instructing the agent to call other tools (buscar_contato, buscar_usuario, etc.) before using this tool, which gives clear guidance on required preparatory steps. It also explains pagination and ordering usage. However, it does not compare this tool to alternatives like 'buscar_tarefas' or specify when to use this tool versus others.

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