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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds a genuine provenance caveat ('Vem da base inicial do histórico; as datas vêm do cabeçalho'), warning that data may be partial — useful, though cryptically worded and silent on pagination or completeness limits.

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 short sentences, front-loaded with the dual capability, followed by a single provenance caveat. No filler and nothing repeated from the title.

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?

Covers both query modes for a tool with five optional parameters and no required ones, which is the key thing an agent needs. The one gap is that it never says what happens if neither referencia nor signatario is supplied, leaving the zero-argument path undefined.

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 100%, including the enum for formato and the mutual-exclusion note on referencia/signatario, so the schema carries the parameter semantics. The description adds nothing about formato, limite or cursor beyond what the schema already states; baseline 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?

States a specific verb and resource with two clear modes: 'Mostra quem assinou uma norma (autor, coautores e origem da autoria)' or 'lista as normas de um signatário'. An agent can tell this returns authorship data rather than norm text, but the description never names or contrasts with siblings like leis_obter or leis_buscar.

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 'ou' structure implies two usage paths and the description hints at choosing referencia vs signatario, but that routing is already spelled out in the schema. There is no explicit when-not guidance nor any mention of the sibling tools that overlap (e.g., obtaining the norm itself).

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description goes beyond them by describing the returned item shape (path, título, tipo, número, data, UF, ementa, situação, fonte, versao_texto, baixado_em, OCR flag) and pagination via cursor, which matters because there is no output schema; it stops short of noting ordering or result-size behavior.

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, front-loaded with the purpose before the return shape and pagination note. The field enumeration is long but justified given the absence of an output schema; otherwise there is 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 15 optional parameters, full schema coverage and rich annotations, the description fills the main remaining gap — what comes back and how to page — which is exactly what a query tool needs absent an output schema. Minor omissions like result ordering or behavior when no filters are supplied are low-stakes.

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 100% and the schema already documents every parameter with examples, enums and defaults (including the 'sem texto, lista pelos filtros' rule and alcance modes). The description only gestures at 'palavras e filtros' and the cursor, so it adds no parameter meaning beyond the schema — baseline 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?

States a specific verb and resource ('Busca normas') and scopes it to the local corpus ('acervo local'), which is meaningfully different from a web search. It does not name or differentiate against siblings like leis_obter or leis_facetas, so an agent must infer that this is the search/list entry point versus a single-record fetch.

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?

Usage is implied by 'por palavras e filtros', and the description adds a procedural hint about using the cursor for the next page. However, it never states when to choose this over leis_obter or leis_facetas, nor any exclusions or prerequisites, leaving routing between siblings to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false. The description adds real context beyond them: it reveals the underlying artifacts read (COBERTURA.md, PROGRESSO.md, _falhas.jsonl) and enumerates the reported fields, so the agent knows this is a local-state diagnostic rather than a live query.

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?

One sentence, front-loaded with what is produced and backed by a parenthetical of concrete outputs. The embedded file names are semi-implementation detail but serve as evidence of what is being read, not 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 must sketch the return value, and it does (commit, data do sync, escopo, totais) while framing the tool as a read-only coverage check. What the 'recorte' filters actually do is left to the 100%-covered schema, which is reasonable.

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 100% with 6 optional filter parameters, each documented with examples and one enum. The description only gestures at them through 'recorte' and 'escopo' without explaining how uf/tipo/orgao/esfera/tribunal/municipio narrow the slice, so baseline 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?

States a specific verb ('Mostra') and a specific resource (lacunas de um recorte plus local index state: commit, sync date, scope, totals). This clearly separates it from the retrieval siblings (buscar, obter, facetas, autoria), though it never names them 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?

Usage is only implied: the agent infers it should call this to check coverage gaps or index freshness. There is no explicit 'use when' statement, no exclusion criteria, and no pointer to a sibling for the alternative case.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, covering the safety profile. The description adds the useful cross-reference that filters mirror leis_buscar, but it does not clarify return shape or how 'limite' interacts across multiple dimensions, which matters for a 13-parameter aggregation tool.

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?

A single front-loaded sentence that states the action, dimensions and filter relationship with zero filler. Every clause carries information.

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 read-only aggregation tool with a fully documented 13-parameter schema, the description is adequate but thin: it never states that the result is counts grouped per requested dimension or how 'limite' caps each dimension's bucket, and no output schema exists to fill that gap.

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%, so a baseline of 3 applies. The description earns extra credit by asserting the filter set is the same as leis_buscar, which conveys semantics (matching/filtering behavior) the schema itself does not state, and its dimension list corroborates the 'dimensoes' enum.

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?

States a specific verb ('conta') and resource ('normas'), and enumerates the exact dimensions aggregated (esfera, tipo, UF, órgão, tribunal, município, década). It also distinguishes itself from the sibling leis_buscar by positioning itself as the counting counterpart with the same filters.

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 phrase 'com os mesmos filtros de leis_buscar' implicitly tells the agent to use this tool when aggregates are wanted instead of document listings, and that filter semantics are shared with the sibling. However, there is no explicit 'when not to use' or a direct statement contrasting it with leis_buscar in an imperative form.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description adds real behavior beyond that: struck-through text is omitted by default with a warning, pagination is per article, and ambiguous citations return candidate matches instead of failing. It does not say what a paginated response contains beyond the cursor reference.

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 short sentences, front-loaded with the core action and mode, then the default omission behavior, then the ambiguity fallback. 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?

For an 11-parameter read tool with full schema coverage and annotations, the description covers the key decision points (reference forms, whole-norm vs. article, struck-text default, ambiguity). The main gap is return shape — e.g., that the response carries a next cursor — which is left to the parameter docs.

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 100%, so every parameter (uf, esfera, bloco, artigo precedence, cursor, incluir_tachado) is already documented in the schema. The description only restates the reference forms and the pagination mode, adding no syntax or precedence detail beyond what the schema provides — baseline 3.

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?

States a specific verb (lê) and resource (norma/dispositivo) plus the accepted reference forms (caminho, URN, citação) and the two read modes (inteira paginada por artigo vs. dispositivo isolado). It does not name the sibling leis_buscar in the description itself, so differentiation from search is only implied (the path link appears in the schema).

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?

Usage is implied: this is the retrieval tool for a known norm, as opposed to searching. The ambiguous-citation fallback ('devolve candidatos') tells the agent what happens but not explicitly when to prefer leis_buscar over this tool or how to recover from ambiguity. No explicit exclusions.

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