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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so there is no contradiction. The description adds that this is a state-level lookup by identifiers, but it does not disclose response format, data source, per-state variability, or any required authentication. Beyond the safety profile, behavioral detail is thin.

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 a single compact sentence that names the certificate type, the query keys, and the required input. It is front-loaded with the essential concept and contains no filler or redundant restatement of the tool name.

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?

For a simple read-only query tool with annotations covering safety, the description gives enough to select it, but not enough to invoke it with confidence: it does not specify whether at least one of CNPJ/CPF/IE must be supplied alongside UF, nor what the return value looks like. Since there is no output schema, this gap matters for successful use.

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 add meaning by telling the agent that UF is the required state indicator and that CNPJ/CPF/IE are the query keys. However, it does not clarify whether CNPJ, CPF, and IE are mutually exclusive, which one applies to a given entity type, or what formats are expected, leaving ambiguity for invocation.

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 clearly identifies the tool as a query for a state-level negative debt certificate (CND estadual) using CNPJ/CPF/IE and requiring the UF. It distinguishes itself from siblings like consultas_cnd_federal by explicitly saying 'estadual' and 'de um estado', and 'Informe a UF' gives immediate scope guidance.

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 implies when to use it: when a state-level CND is needed and the UF is known. It does not explicitly name alternatives like consultas_cnd_federal or explain when not to use it, but the state/federal distinction is clear from the wording. This is enough for basic selection but lacks explicit exclusion guidance.

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