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

Annotations already declare readOnly, idempotent, non-destructive behavior, and the description adds important context beyond them: precos is null when fewer than 3 softwares publish a price, raio_x is null when fewer than 3 profiles exist, and each number carries its definition and base. This nullability and provenance disclosure is exactly the kind of behavioral detail annotations cannot convey.

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 dense opening sentence front-loads the returned metrics, followed by null-threshold rules and usage guidance in a logical order. It is long but nearly every clause carries distinct information; the enumeration of metrics could be tightened slightly.

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 enumerates the return fields, explains when sections are null, mandates citing the source URL and date, and points to listar_categorias for the input. An agent has everything needed to call it and correctly present results.

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% and the single categoria parameter is fully documented in the schema with an example slug and a pointer to listar_categorias. The description adds no further syntax or format guidance, so the baseline of 3 applies.

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 a specific resource (category statistics derived from published profiles) and enumerates exactly what is computed: price counts, min/median/max price per user and per company, free plan and trial, cheapest plan, and technical-profile coverage. This is far more specific than the sibling names imply and lets an agent tell it apart from listar_categorias or buscar_softwares.

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 explicit trigger conditions: 'Use quando a pessoa perguntar quanto custa um tipo de software, quantos publicam preço ou quantos têm um recurso.' It also specifies a follow-up requirement to cite url_canonica and the date. It stops short of naming sibling alternatives to route away from, which keeps it below a 5.

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