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

Annotations already establish readOnly, non-destructive, closed-world behavior, and the description adds the key authorization trait: without target_user_id it searches the authenticated account, and only the platform admin may cross into a client account. It does not describe result ordering or truncation beyond what 'most relevant excerpts' implies.

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?

Three tight sentences with the core action and return value front-loaded, followed by usage context and the permission scoping note. No filler.

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 compensates by stating it returns relevant excerpts, and it covers the auth scoping case. What remains (limit/pagination behavior, tag filtering) is adequately handled in the schema, so only minor gaps remain.

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 100%, including descriptions for tag, limit, query, and target_user_id, so the baseline is 3. The description restates the target_user_id admin restriction and default rather than adding syntax or format detail beyond 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 names the specific operation (busca semântica), the resource (base de conhecimento do usuário), and states what it returns (os trechos mais relevantes). It is clearly distinguishable from write-oriented siblings like create_kb_document and from list_kb_documents.

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 gives concrete usage context ('Use para responder perguntas sobre produtos, serviços, procedimentos') and explains the target_user_id scoping case, but it never explicitly states when to prefer list_kb_documents over this tool, leaving one inference for the agent.

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