Buscar nos documentos

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds genuinely non-obvious behavior: matching is accent- and case-insensitive and requires all words on the same line, plus the return shape (file, line, short excerpt). One tension worth noting: annotations say openWorldHint=true while the description emphasizes a 'local' document set, which reads as closed-world; this is a mismatch of emphasis rather than a direct contradiction.

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, both dense with unique information: the first covers scope, matching rules and return shape; the second covers the usage trigger. Nothing is redundant and the search semantics are 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?

With no output schema, the description correctly discloses what comes back (file, line, excerpt), and it explains the matching model and when to call it. The only real gap for a 2-parameter search tool is the undocumented limit/pagination behavior and whether results are capped or ranked.

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 only 50% (limit has no description), so the description has to compensate, and it does for the required parameter: it defines the matching semantics (accent/case insensitive, all words must appear on the same line) that the schema's 'Words to search, in pt-BR' does not convey. The 'limit' parameter and any default result count remain undocumented in both places.

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 gives a specific verb and resource: 'Search the local company knowledge documents'. The qualifier 'local company knowledge documents' separates it in substance from siblings like aspa_search_conversation and aspa_search_contact, though it never names those alternatives explicitly.

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 states a clear usage trigger: 'Use it before stating facts about the company in a draft.' That is real when-to-use guidance tied to an agent workflow. It stops short of when-not-to-use conditions or naming aspa_read_knowledge / aspa_search_conversation as the alternative for adjacent needs.

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