acervo-juridico

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

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=true) by disclosing that authorship is derived from the token rather than the body, that declared sources and probabilities are not certified, that the repeat-request ID behavior holds, and that no code is executed. These are material facts an agent could not infer from the structured fields.

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?

Front-loaded with the verb and resource, then a chain of short factual sentences covering auth, authorship, certification caveat, and idempotency. Dense but every sentence carries information; 'Reutiliza autoria e persistência social' is the one vaguely worded clause that slightly dilutes it.

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 the hard parts for a write tool with rich annotations and an output schema: auth requirements, identity derivation, trust caveats on sources, and idempotency. Gaps remain around the perguntar/responder action modes and the duvida_id linkage, which are the main things an agent could still get wrong.

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?

With only 13% schema description coverage, the description must carry real weight; it does explain chave_idempotente semantics, the tese/antítese/síntese positions, and the non-certified nature of fontes and probabilidades. However, it says only 'Publica' while the schema's acao enum allows perguntar and responder, and it never mentions duvida_id, resposta_automatica, or the array limits, leaving substantial documented surface untouched.

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 ('Publica') and resource ('debate jurídico br.lex.1') plus the payload it carries (tese, antítese, síntese, fontes, chave_idempotente), so an agent knows exactly what operation this is. It does not explicitly differentiate itself from siblings like responder_pergunta or participar_rede_social, which is why it stops short of 5.

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?

Gives concrete preconditions: machine OAuth scope 'redesocial:participar' and a profile already created via participar_rede_social, which effectively points at a sibling as prerequisite. It also states the idempotency contract (repeating the request preserves the ID). No explicit when-not-to-use or guidance on choosing between publicar/perguntar/responder.

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 readOnly, non-destructive, closed-world, non-idempotent, so the safety profile is covered. The description still adds real context beyond them: it requires OAuth scope 'pesquisa:consultar', touches local originals, produces no publication, and explicitly disclaims certifying legal truth, vigência or merit — a meaningful boundary for a legal-evaluation 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?

Three compact sentences, with the tool's nature and output commitment ('sem publicação') front-loaded, followed by the checked criteria, the access/auth requirement and the scope caveat. The criteria list is telegraphic ('refutações explícitas, fontes sem recibo, adulteração') but nothing is wasted.

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?

An output schema exists, so return values need not be explained, and the description covers safety, auth scope, access to local originals and explicit exclusions. What is slightly thin is the outcome semantics — whether the analysis yields a verdict, a list of defects, or blocks publication — plus any failure/error behavior.

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?

Only one parameter, and the schema itself documents it ('Debate tipado br.lex.1; usa tese, antitese, sintese e fontes documentais declaradas') at 100% coverage, so the baseline is 3. The description adds indirect meaning by naming the fields it inspects (receipts, acquisition date, refutations), but it does not explain the debate payload or its required keys directly.

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 operation — a deterministic pre-analysis (without publication) that checks for explicit refutations, unreceipted sources, tampering, acquisition-date proof and absence of adversarial counter-argument. That is far more than a restatement of the title, though the verb ('avaliar') is only implied through the list of checks rather than stated outright, and no sibling is named. An agent can broadly tell what the tool inspects.

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?

'Pré-análise determinística sem publicação' implies a pre-publication gate and the closing 'Não certifica verdade jurídica, vigência ou mérito' implicitly routes validity questions to avaliar_vigencia_normativa. But no sibling is named and there is no explicit statement of when to use this versus alternatives such as pesquisar_casos or avaliar_vigencia_normativa.

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, destructiveHint=false and openWorldHint=false, yet the description adds real context: authenticated access, content-addressed receipts, the required scope, and the crucial semantic that the response distinguishes documented fact, contradiction and legal uncertainty without inferring vigencia. That last point is behavior no annotation conveys.

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?

Four sentences, front-loaded with the resource and scope, with no filler. The critique sentence is dense but every clause is actionable, and the output contract is stated clearly.

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?

An output schema exists, so return structure need not be described; the description still covers auth scope, the operation vocabulary and the evidentiary semantics. What is missing is any hint of what this tool is not for relative to the many retrieval siblings.

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 a baseline of 3 would be defensible, but the description goes further: it enumerates the legal values of the generic op string (node/timeline/as_of/unresolved/critique) and the allowed predicates (publicado_em, data_ato, alterado_por, fonte_vinculada, vigente_em) that the schema leaves as free text. This meaningfully constrains parameters that the schema leaves open.

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 verb and resource: an authenticated historical query over Resolução CNJ 615/2025, with content-addressed sources and receipts. That is far more precise than a generic search tool, but it never names the neighboring tools such as consultar_temporalidade, mudancas_desde or grafo that an agent should also consider.

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 explains what to send in consulta_grafo (node, timeline, as_of, unresolved, critique, with id and up to 8 typed alegacoes) and states that scope pesquisa:consultar is required. However, it never says when to choose this tool over siblings like consultar_temporalidade or avaliar_critica_brlex, so routing guidance exists only by implication.

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=true, so the safety profile is covered. The description adds useful behavioral context: results are thread paths, content is reader questions answered by verified lawyers, and the tool returns data intended as input for ler_duvida. This goes beyond what annotations alone provide, though it stops short of describing pagination or ordering 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?

The description is compact and front-loaded: it states what the tool searches, what it returns, how the result is used, and how it differs from the sibling tool. Every sentence earns its place without repetition.

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 search tool with a complete input schema and an output schema, the description covers the purpose, result format, domain, and sibling relationship. The note that thread paths feed into ler_duvida completes the practical invocation flow.

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 parameter descriptions are already meaningful, including an example for 'consulta' and constraints for 'limite'. The tool description itself does not add much parameter-level detail, so the baseline 3 is appropriate.

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 uses a specific verb ('Busca') with a clear resource ('dúvidas jurídicas publicadas na rede social do portal') and states the language scope ('em português'). It also distinguishes itself from buscar_paginas by explicitly separating reader-generated content from editorial content.

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 names the alternative tool (buscar_paginas) and gives the criterion for choosing: reader Q&A content goes here, editorial content goes to buscar_paginas. It also explains that the returned thread paths feed into ler_duvida, giving clear downstream context.

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 establish readOnly and closed-world, and the description adds real context beyond them: no external model is called, deeper search widens candidates per index without increasing result count, and ranking may change with no guarantee of better relevance. It leaves result ordering and pagination behavior unstated, but that is largely covered by the output schema.

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?

Information is front-loaded with the mechanism first, then the caveat, then the follow-up pointer to ler_pagina. The sentences are dense but each carries a distinct fact; minor redundancy exists between the description and the profundidade schema text.

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 a full output schema and solid annotations, the description supplies what structured fields cannot: the fusion mechanism, the closed-world/no-external-model guarantee, and the risk profile of the tuning parameter. Nothing essential for correct invocation appears missing.

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 the baseline is 3; the description earns an extra point by explaining the operational trade-off of profundidade (only for low-coverage investigation, ranking instability, no guaranteed gain) rather than restating its bounds. The pergunta and limite parameters are left entirely to the schema, which is acceptable at full coverage.

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 operation: it fuses lexical and semantic local search by RRF (k=60) and returns sources, positions, indices and states. The word 'híbrido' plus the fusion mechanism clearly separates it from purely semantic or page-lookup siblings, though it never names buscar_semantico or buscar_paginas 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?

Gives a clear conditional rule for the optional profundidade: only when investigating low coverage, with the warning that the ranking may shift and improvement is not guaranteed. It also routes the agent to ler_pagina for verification, but does not state when to prefer this over the semantic-only sibling.

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=true and idempotentHint=false, so the safety profile is covered. The description adds useful behavioral context by disclosing that results are canonical paths feeding ler_pagina, but says nothing about result ordering, corpus breadth, or why the call is non-idempotent despite being read-only.

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 tight sentences, zero redundancy, with the purpose front-loaded and the hand-off to ler_pagina placed second. 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?

With an output schema present and 100% parameter coverage, the description need not explain return values, yet it still names the canonical-path output and the next tool. The only meaningful gap for an agent is disambiguation from the many sibling search tools.

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 both parameters (consulta, limite) are already documented in the schema, including the default of 8 and the possibility of covering the whole corpus. The description only reinforces that the query is in Portuguese and subject-based; 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 páginas do acervo jurídico brasileiro') plus the scope ('por assunto, em português'), and points at the downstream consumer ler_pagina. It does not differentiate itself from the many sibling search tools (buscar_semantico, buscar_hibrido, search, pesquisar_fontes), which is the main remaining ambiguity.

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 second sentence establishes the search-then-read workflow with ler_pagina. There is no explicit statement of when to prefer this over buscar_semantico or buscar_hibrido, nor any exclusion or prerequisite, leaving the agent to infer selection among near-identical siblings.

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=true and openWorldHint=false, and the description adds meaningful context: how the ranking is produced (cosine over the same embedding model) and what the output is used for. It does not discuss ranking scores, thresholds, or how 'limite' interacts with corpus size, but the safety profile is already covered by annotations.

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 dense sentences with zero filler: mechanism and contrast first, then the usage rule and downstream handoff. Nothing repeats the name or 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?

With annotations and a full output schema present, the description covers mechanism, selection and follow-up. Minor gaps: no note on how results are ordered when 'limite' is large, or what happens when no page passes a similarity bar.

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 'pergunta', 'area' and 'limite' are already documented with examples and defaults. The description adds no per-parameter syntax or constraints beyond the schema, so the 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 páginas do acervo pelo SIGNIFICADO') and explains the mechanism (query embedded as vector, cosine nearest neighbors). It explicitly sets itself apart from the lexical sibling buscar_paginas, so an agent can choose without opening either 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?

Gives an explicit selection rule: use it when buscar_paginas (lexical) fails because the vocabulary differs. It also names the downstream step - the returned paths are input for ler_pagina - completing the workflow.

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 cover safety (readOnlyHint=true), and the description adds real epistemic behavior: the five temporal layers it separates, that unknown dates and concurrent versions are surfaced explicitly, and that a result does not certify global legal validity. That is substantive disclosure beyond the structured fields, though it says nothing about result volume or ordering.

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 dense sentences, front-loaded with the query axes before the interpretive caveats. No filler; each sentence adds a distinct layer of 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?

A five-parameter required-query tool with an output schema, so return values need not be described. The description supplies the conceptual model (bitemporal separation, explicit unknowns, no certification of validity) that an agent needs to interpret results correctly; the only residual gap is identifier formatting.

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% with five required parameters, so the description must carry the load. It does name all five concepts and gives the RFC3339 format for known_at while implicitly contrasting fact_date (event time) against known_at (knowledge time), but it gives no format or expected shape for act_id or provision identifiers.

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 (bitemporal query) plus the exact axes it queries over: act, provision, jurisdiction, fact date and known_at. An agent understands what it retrieves, though it never names which sibling (e.g. avaliar_vigencia_normativa or mudancas_desde) it should be preferred over.

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 the use case (resolving how a provision stood at a given fact date as known at a given time) and explicitly warns that absence of a result is not proof of non-existence. But it offers no explicit when-to-use/when-not framing against the many temporal and normative siblings, leaving routing 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?

The annotations already declare readOnlyHint=true, openWorldHint=false and idempotentHint=false, so the description does not need to establish safety. It adds real behavioural context: 'Nada é gerado: cada bloco é o que a página publicada afirma, com a URL para conferir', a no-generation grounding guarantee. It also describes how retrieval is assembled, combining semantic search when armed with lexical search.

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 three dense sentences: it states the purpose first, then the composition of the output, and ends with a grounding guarantee. Every clause carries information, and no wording repeats the title or the schema.

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?

An output schema exists and the annotations cover the read-only profile, so the return shape and safety profile need no explanation. The description still tells the agent what the blocks are grounded in and how retrieval is fused, which is the remaining gap for an aggregation tool. Only sibling differentiation is missing.

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 the schema already documents pergunta, area and paginas (including the default of 3 and the cap of 8). The description adds only the loose phrase 'para cada página relevante' and never explains the area filter or the page cap. Baseline 3 applies because the schema does the heavy lifting.

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 uses a specific verb and resource ('Monta o contexto jurídico denso para uma pergunta') and then enumerates what the result contains: tese, dispositivos com URN LexML, precedentes, fontes com data de conferência and a citação pronta. This makes the tool's output shape unambiguous. However, it never names a sibling tool, so the agent must infer by itself how this differs from buscar_hibrido, buscar_semantico or responder_pergunta.

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 tool is for a legal question, and it 'junta a busca por significado (quando armada) com a lexical', which hints at its relation to the semantic and lexical search siblings. The description nonetheless gives no explicit when-to-use rule, no when-not to use it, and it never names an alternative tool; the agent has to infer selection.

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?

The readOnly annotation already covers safety, and the description adds useful scoping about how the theme is identified. However, it does not disclose what happens when no identifier is provided or when both caminho and area+tema are supplied, and it leaves list ordering/pagination behavior unstated beyond what the schema covers.

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 compact sentences, front-loaded with the action and resource, followed by the identification modes and the value proposition. There is no filler, and the bridge metaphor earns its place by clarifying when the tool is useful.

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?

The output schema and readOnly annotation reduce the burden for return values and safety. What keeps it from being complete is the unresolved all-optional schema: the description implies an identifier is needed but never states behavior for no arguments or conflicting identifiers, and it omits any pointer to buscar_duvidas as the search-oriented alternative.

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 the baseline is 3, and the description adds meaning by explaining the alternative relationship between caminho and area+tema and by tying caminho to ler_pagina's route. The limite parameter is left to the schema, which is acceptable since the schema already documents it.

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 states the tool lists reader questions ('dúvidas') about a theme, with a specific verb and resource. It also grounds the theme identifier in ler_pagina's returned route, but it does not explicitly distinguish itself from the sibling buscar_duvidas.

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 provides clear context: use this when you have a theme from the acervo, identified by caminho or area+tema, and want the real questions readers discuss. It positions the tool as a bridge between the editorial acervo and reader questions, but it does not name exclusions or a preferred sibling alternative such as buscar_duvidas.

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 readOnly/idempotent/non-destructive; the description adds value beyond them by stating public authorship, sources, and hashes of discussions, that no credential is required, and that cursor continuation preserves history. A minor gap is that it doesn't clarify pagination limits or what 'hashes' contain, but the safety-relevant context is well covered.

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 dense and front-loads the read capability, but packs multiple concerns (resource enumeration, conditional rules, recommendation behavior, cursor usage) into a tight block. The 'Recomenda próximos assuntos' sentence introduces a second capability that dilutes focus, and the proximo_cursor naming slip costs clarity.

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?

An output schema exists, so return values needn't be explained, and the conditional parameter rules help. But with 8 parameters and only 25% schema coverage, four parameters (area, assunto, tema_id, limite) are effectively undocumented across both schema and description, leaving the definition incomplete for correct invocation.

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 25%, and the description usefully adds the conditional requirements (comentarios exige post_id, respostas exige duvida_id), which are not encoded in the schema. However, it leaves area, assunto, tema_id, and limite unexplained, and references 'proximo_cursor' while the actual parameter is named 'cursor', which is a confusing mismatch.

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 states a specific verb ('Lê') and enumerates the resources (publicações, comentários, perguntas, respostas) as well as a recommendation capability. It reads as a broad 'explore the community' endpoint and does not explicitly distinguish itself from siblings like buscar_duvidas or ler_duvida, but the resource list makes the scope clear.

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 through the resource enumeration and 'Recomenda próximos assuntos por tema, termos e área', which hints at discovery use. However, the description never says when to prefer this tool over buscar_duvidas, ler_duvida, or participar_rede_social, leaving sibling selection 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=true, so the safety profile is covered. The description adds that the tool returns full text and a citation URL, which is light behavioral context. It does not discuss errors, rate limits, or the fact that idempotentHint=false is set despite a read-only operation.

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, focused sentence that front-loads the verb and object and states the id source. There is no unnecessary repetition or boilerplate.

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 one-parameter read tool with an output schema and read-only annotation, the description is nearly complete. It covers the core operation and the id provenance. The only notable gap is lack of guidance on how this relates to the sibling 'ler_pagina', which could confuse an agent choosing between them.

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 explains that 'id' is the canonical page route returned by search. The description restates this dependency but adds no new parameter-level details. 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?

The description uses a specific verb ('Devolve') and resource ('texto integral de uma página do acervo'), and specifies that the identifier comes from 'search'. It is clear what the tool does, but it does not explicitly distinguish this from the sibling 'ler_pagina', which appears to perform a similar read operation.

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 conveys a clear prerequisite: use the id returned by search. This gives the agent context about when to call the tool. It does not mention alternatives or exclusions, so it falls short of a 5.

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 provide readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral detail: it returns both the entity and its typed relationships, accepts exact keys or label terms, and returns alternatives when there is more than one candidate rather than failing. No contradiction with the annotations.

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 two dense, front-loaded sentences with no filler. It presents the core result first, then the query modes and ambiguity handling. The enumerations of entity types and relationship types are relevant and concise.

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?

Given the rich input schema and the presence of an output schema, the description covers all selection-relevant details: entity types, relationship types, key formats, label search, and candidate disambiguation. Nothing critical is missing for an agent to select and invoke the tool correctly.

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?

The input schema already has 100% coverage with detailed descriptions, including exact key formats for entidade and bounds for limite. The description still adds value by confirming the accepted query modes and explicitly describing the multiple-candidates behavior, which goes beyond the schema-only baseline.

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 uses a specific verb ('Devolve') and a specific resource ('grafo de conhecimento jurídico'), enumerates the entity types and relationship types returned (cita, pertence_a, revoga, julgado_por, da_area), and explains the two query modes. This clearly distinguishes it from generic search or fetch siblings.

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 clearly frames when to use the tool: when you need a legal knowledge-graph entity and its linked neighbors, using either an exact key or a label term. It also explains the ambiguity-handling behavior. However, it does not explicitly name sibling tools or state when not to use them, so it stops short of full routing guidance.

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?

The annotations already declare readOnlyHint=true, so the agent knows it is a safe read operation. The description adds meaningful behavioral context by explaining exactly what is returned (pages and acórdãos citing the same devices) and the 'grau' concept, which goes beyond the structured annotation data without contradicting it.

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 two well-organized sentences: the first front-loads what the tool does and the output, the second explains the practical cascading use case. Every sentence contributes necessary orientation with 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 a read-only list tool with an output schema and fully documented parameters, the description is complete. It identifies the supported entity types, the nature of results, and the intended use case, so an agent has enough context to invoke it correctly.

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 both 'entidade' and 'limite' are already documented in the input schema. The tool description refers generically to 'norma, dispositivo, súmula, tema ou acórdão', matching the schema's examples, but it does not add new parameter-level meaning beyond what the schema already provides.

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 starts with a specific verb and resource: 'Lista quem se apoia numa norma, dispositivo, súmula, tema ou acórdão', then specifies the output as pages and STJ acórdãos with a degree of overlap. It clearly communicates the tool's role as citation-impact analysis, which distinguishes it from sibling search tools like buscar_paginas or search.

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 provides a concrete usage scenario: 'É a base do efeito cascata: decisão nova sobre um dispositivo → páginas a rever.' This tells the agent when to use the tool, but it does not explicitly mention when not to use it or name alternative tools for similar cases.

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?

Beyond the annotations, the description discloses the return format (Markdown), the canonical source URL, and the answer-level details: author, verified OAB registration, and cited official sources. It does not explain error behavior or why idempotency is false, but with readOnly and openWorld annotations already present, this is useful added context.

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 two compact sentences, front-loading the core behavior and then adding the canonical-URL detail. Every sentence contributes directly to identifying the tool and understanding its output.

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?

Given the simple one-parameter schema, 100% schema coverage, existing output schema, and read-only annotations, the description supplies everything needed: what is returned, in what format, and what each answer contains. No essential call-time information is missing.

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 explains that the parameter accepts a slug or the full path returned by buscar_duvidas. The description does not add syntax or format details beyond what the schema provides, so the baseline 3 is appropriate.

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 states a specific verb and resource: it returns a single social-network question together with all published answers, in Markdown. The mention of the canonical URL and answer contents clearly distinguishes it from search/list siblings such as buscar_duvidas.

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 tool for reading one full dúvida and its published answers. However, the description does not explicitly say when to use it instead of buscar_duvidas or duvidas_do_tema, nor does it name exclusions or prerequisites.

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=true, so safety is covered; the description adds useful content-level context by naming the sections, FAQ, and URL-bearing sources that come back and framing their verification purpose. It says nothing about failure modes (invalid/non-canonical path, missing page) or result size, which matter for a fetch-style 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?

One front-loaded sentence stating the action, the format, and the payload. The trailing clause about verifying claims earns its place as a usage cue, though the em-dash aside is slightly verbose.

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 an output schema present, the description needn't enumerate return fields, and it still gives a useful shape of what's inside (sections, FAQ, sourced URLs). For a one-parameter read-only tool this is nearly complete; only error/edge behavior is absent.

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 single 'caminho' parameter is fully documented in the schema (canonical route with trailing slash, example given). The description adds no parameter detail beyond that, 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?

Names a specific verb and resource ('Lê uma página do acervo') and the returned format (Markdown), plus the payload contents (seções, perguntas frequentes, fontes oficiais com URL). It doesn't explicitly differentiate itself from siblings like buscar_paginas or ler_duvida, but the read-single-canonical-page scope is inferable.

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?

Implies it is used to open a page obtained from search and to verify what the page asserts via its official sources, but never states when to prefer it over buscar_paginas or ler_duvida, nor any exclusions or prerequisites.

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?

The annotations already mark the tool read-only, and the description adds valuable behavioral context: ascending date order, cursor-forward pagination, and the termination condition on restantes. No contradiction with annotations exists.

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 carry the full operational model: purpose, audience, ordering, and pagination loop. The core behavior is front-loaded and every clause earns its place.

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?

The tool has a rich schema, an output schema that presumably defines proximo_cursor and restantes, and read-only annotations. The description fully explains how to start, continue, and terminate pagination, making the tool complete for an agent without further inference.

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 both cursor and limite are already explained in the schema. The description reinforces the cursor usage pattern but does not add substantial new parameter-level meaning beyond what the schema provides.

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 uses a specific verb ('Lista') and resource ('páginas do acervo revisadas'), adds ordering and pagination semantics, and clearly identifies itself as a change feed. This distinguishes it strongly from sibling search/read tools like buscar_paginas and ler_pagina.

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 clear context for when to use the tool ('para quem mantém cópia ou índice do acervo') and an explicit pagination recipe: start with an ISO date or empty, then repeat with proximo_cursor until restantes is 0. It does not explicitly name alternatives or exclusion cases, so it stops short of a 5.

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?

Adds real context beyond annotations: the required machine-token scope redesocial:participar, the caveat that papel_de_estudo confers no professional habilitação, and the idempotency mechanism (stable chave_idempotente means repeats don't duplicate). That last point substantiates rather than merely repeats the idempotentHint=true annotation.

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?

Four dense sentences, each carrying distinct information (purpose, auth, ordering, idempotency, alternative), with purpose front-loaded. No filler, though the sentences are packed tightly enough to deserve a slightly lower mark than perfect.

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?

Output schema exists so return values need not be explained, and safety traits are annotation-covered. But for a 15-parameter, multi-action tool, the description never maps the five acao values to their required parameters, leaving an agent to infer which fields belong to perfil vs publicar vs responder.

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 33% across 15 parameters. The description clarifies chave_idempotente, papel_de_estudo, and the acao=perfil prerequisite, but area, corpo, titulo, midias, fontes, audio, video, post_id, tema_id, and duvida_id have no documentation in either schema or description, and no mapping of which parameters apply to which acao value is given.

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 specific verbs (cadastra perfil, publica estudos/comentários/perguntas/respostas) against a concrete resource (rede jurídica), and explicitly distinguishes the read path by naming explorar_comunidade. An agent can tell this is the write-side social tool without opening 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?

Gives an explicit precondition (use acao=perfil before publishing) and names the alternative for exploration (explorar_comunidade). It does not address the overlap with the sibling responder_pergunta for the acao=responder path, so the routing guidance is strong but not complete.

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?

Beyond the readOnlyHint=true annotation, the description discloses a meaningful behavioral constraint: it deliberately omits rankings and counts that could enable professional comparison, citing OAB Provimento 205/2021. It also clarifies that the OAB inscription is returned only 'quando verificada', which is useful data-quality context.

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 tight sentences: the first front-loads the positive return fields, and the second immediately states what is not returned and why. There is no filler or repetition of schema content.

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 single-parameter read-only profile lookup with an output schema and clear annotations, the description covers purpose, return fields, exclusions, the verification caveat, and regulatory rationale. Nothing essential is missing.

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 required parameter 'handle' is already documented with 'sem arroba'. The description adds no extra parameter-level meaning, so the baseline score 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 the exact resource ('perfil público de quem participa da rede') and enumerates the returned fields: nome, apresentação, OAB inscription when verified, and follower count. It also explicitly distinguishes itself from comparison/ranking tools by stating it does not return rankings, response volume, or other comparative counts.

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 clearly implies use when a public jurist profile is needed and warns that this tool is not for ranking or comparison metrics. However, it does not name an alternative sibling tool or explicitly say 'use X instead', so the routing guidance is strong but not fully explicit.

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?

With readOnlyHint=true already provided, the description adds useful behaviorally relevant context: it returns HTML/JSON/Markdown links and a SHA-256 hash of the source, and it warns that DataJud results do not contain party names. It does not address idempotency despite idempotentHint=false, but the added disclosure is substantive.

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 two compact sentences, front-loaded with the core purpose and followed by return-format and data-limitation notes. Every clause earns its place and there is no redundant repetition.

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?

The tool has an output schema, so the description need not explain return structure, and the annotations already establish the read-only safety profile. The description adds the important DataJud party-name limitation and source-integrity information; it is largely complete for an optional-parameter search tool.

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 the schema already documents all eight parameters in detail. The description summarizes the main search dimensions (text, CNJ number, court, STJ relator, period, origin) but does not add syntax, format, or combination guidance beyond what the schema provides; baseline 3 is appropriate.

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 states a specific verb and resource: it searches public CNJ/DataJud cases and STJ acórdãos, and it names the searchable dimensions. It is clear what the tool does, but it does not explicitly differentiate itself from sibling search tools such as buscar_hibrido, buscar_semantico, or search.

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 the domain: this is for public case and STJ acórdão lookup. However, there is no explicit guidance on when to use this instead of the many sibling search tools, and there are no stated exclusions or prerequisites.

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 cover read-only/open-world/non-idempotent/non-destructive, yet the description adds real behavior: SSRF/robots protection, local-only text extraction, cacheable provenance, and the important caveat 'sem certificar vigência' (verifies existence, not validity). It also discloses the operator-token scope requirement, which 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 core purpose is front-loaded, but the remainder is a dense semicolon-chained run-on that packs several distinct modes into one breath, making it hard to parse. It earns its length on information but loses on readability and structure.

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 14-parameter multi-mode tool with an output schema, the description covers modes, prerequisites, and the key validity caveat, leaving return values to the output schema. A bit more on mode-selection precedence would close the remaining 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 description coverage is already 100%, so 3 is the baseline; the description goes slightly beyond by tying parameters to modes (mutually exclusive consulta/ref/source_ref) and framing provas as 1-4 independent partial verifications and referencia_em as a UTC-day existence check without asserting validity.

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: searches external sources via local SearXNG, fetches HTTPS URLs, extracts text, returns provenance. It also enumerates concrete sub-modes (expand ref, list derivatives by source_ref, verify original+receipt+URL). It does not explicitly contrast against likely siblings like fetch/search/buscar_paginas, so it stops short of full sibling differentiation.

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 mode enumeration ('consulta, ref ou source_ref') and the prerequisite ('Exige token de operador com escopo pesquisa:consultar') imply when each branch applies, but the description never says when to prefer this over fetch/search or when not to use it. Usage is implied rather than stated against alternatives.

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?

Goes well beyond the annotations: no network or inference, OAuth machine scope pesquisa:consultar required, offsets in UTF-8, proofs and per-source failures returned, score is not a probability, and the tool does not certify normative vigência. These are exactly the caveats an agent needs and none are derivable from readOnlyHint/idempotentHint.

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?

Front-loaded with the ranking mechanism, then inputs, then outputs, then caveats and auth. Dense but nearly every clause carries information; only the default limit and cap are omitted for the schema to handle.

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?

An output schema exists, so the brief mention of returned offsets, hashes, proof and per-source failures suffices. Auth scope and the non-certification caveat are covered; the only gap is that it does not say when this tool is the wrong choice versus its retrieval siblings.

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 the baseline is 3, but the description adds real meaning: the four source fields must be exact matches, the source list is bounded to 1-4, and referencia_em excludes acquisitions after the UTC day (a semantic the schema leaves undocumented). The limite parameter's default and cap are left to the schema, which is fine.

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?

Opens with a specific verb and resource plus the ranking method (BM25 lexical over literal excerpts, local, no network or inference), which distinguishes it from retrieval siblings like buscar_hibrido and buscar_semantico by mechanism. It stops short of naming an alternative explicitly, so the differentiation is implied rather than routed.

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 prescribes the call shape (query plus 1-4 sources with exact ref, source_ref, receipt_sha256 and url_declarada) and notes referencia_em as optional, which implies usage. But it never states when to prefer this over buscar_hibrido, buscar_semantico or pesquisar_fontes, and no exclusion condition is given beyond the local/verified constraint.

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?

The description substantially goes beyond the annotations by disclosing the OAuth endpoint and scope (scope relatos:escrever, /oauth/token), warning about the credential need, and defining the anti-forgery anchor: the exact quoted excerpt must match what ler_pagina returned. This adds actionable behavioral context that enums and the readOnly/destructive hints alone do not provide. No contradiction with the annotations is present.

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 three sentences long and each sentence earns its place: purpose, authentication requirement, and the critical exact-match anchor. It is front-loaded and free of filler, despite being information-dense.

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?

The description plus the rich input schema fully specify the operation: what the tool does, when to use it, what credential is required, how caminho is canonical, how the trecho_citado de ancoragem must match, and when other fields are intended. The output schema is provided, so return-value details are not missing from coverage artifact.

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?

With 100% schema description coverage, the input schema already fully documents each parameter. The tool description mostly reinforces the trecho_citado rule already present in the schema, rather than introducing new parameter-level details. It adds only a general rationale for the anchor, so the baseline 3 is appropriate.

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 concrete action with a specific verb ('Relata um defeito'), identifies the target resource ('página publicada do acervo'), and lists defect categories (citação legal mal atribuída, fonte divergente, conteúdo desatualizado). It clearly differentiates from sibling tools buscar_paginas and ler_pagina by focusing on reporting, not searching or reading.

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 explains when to use the tool (found a defect in a published page) and the important workflow prerequisite: the quoted excerpt must come from exactly the Markdown returned by ler_pagina. It also states the required credential scope. However, it does not explicitly say when not to use the tool or name an alternative pathway, so it stops just short of a 5.

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?

Beyond the readOnlyHint annotation, the description adds meaningful behavior: no sentence is generated, content is extracted verbatim from published pages, and every excerpt is tied to citations and official sources with a verification date. It does not contradict the annotations, though it leaves the idempotentHint=false annotation unexplained.

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 definition is a single sentence that packs the core action, the no-generation guarantee, and the return content without filler. The em-dash emphasis and all-caps 'EXTRAÍDAS' slightly reduce elegance but every clause earns its place.

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 an output schema present, readOnlyHint=true, and only two well-documented parameters, the description covers the tool's essential behavior and return commitments (extracted quotes, citations, official sources, verification dates). It is complete for invocation, though it would benefit from explicit guidance on when to prefer it over sibling search tools.

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?

The input schema already documents both parameters (pergunta and paginas) with 100% coverage, so the baseline is 3. The description adds no parameter-specific semantic details beyond the schema; it only restates the general question/pages context.

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 action (responds to a legal question in Portuguese), a clear resource (published pages), and a distinctive output (citations, official sources, and the date each source was checked). The emphasized constraint 'nenhuma frase é gerada' differentiates it from search/fetch/ler_pagina siblings by promising an answer, not just retrieval.

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 makes the intended use clear—answering a legal question in Portuguese using extracted quoted sentences—so an agent can infer when to call it. However, it gives no explicit when-not-to-use guidance or named alternatives among the sibling tools.

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=true, covering the safety profile. The description adds that it returns id, title, and URL, and mentions 'standard connector format' which hints at output structure. It doesn't disclose pagination or rate limits, but with readOnlyHint and an output schema present, the additional value is moderate.

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 concise sentences with the primary action and return format front-loaded, followed by a clear routing instruction. No wasted words.

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 single-parameter search tool with an output schema and annotations covering safety, the description covers the essential behavior and distinguishes the sibling. It lacks explicit pagination details, but that's a minor gap given the simplicity.

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 the query parameter is already documented. The description adds no extra semantics beyond what the schema provides, so baseline 3 is appropriate.

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 states the tool searches the Brazilian legal collection and returns id, title, and URL for each page. It explicitly contrasts with buscar_paginas for 'área e trecho', distinguishing it from a sibling tool.

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 provides a clear alternative ('use buscar_paginas') for a different use case (area and excerpt), giving guidance on when not to use this tool. It doesn't elaborate on other contexts, but this is sufficient for the primary distinction.

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