acervo-juridico

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 mark the tool as read-only, and the description reinforces a non-mutating search behavior. It adds valuable behavioral context by disclosing that results are canonical paths meant to feed into ler_pagina. No contradictions with annotations were found.

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 only two sentences, with the main purpose and scope in the first sentence and the key output behavior in the second. Every phrase earns its place, and it is front-loaded with the most decision-relevant 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 simple read-only search tool with two parameters, full schema coverage, and an output schema available, the description is largely complete. It explains what to search, in what language, and how to use the returned canonical paths. The only notable gap is lack of explicit guidance on how this tool compares to sibling search tools, though that is not essential for basic 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 description coverage is 100%, and the schema already documents both 'consulta' as a Portuguese question/terms and 'limite' as a max results cap with default 8 and ceiling 25. The description's 'por assunto' and 'em português' reinforce the intended query semantics but do not add substantial detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Busca páginas do acervo jurídico brasileiro por assunto, em português.' It also differentiates itself from sibling tools by specifying that it returns canonical paths intended as input for ler_pagina, which helps an agent distinguish it from buscar_duvidas or buscar_semantico.

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 clear context for when to use the tool: searching the Brazilian legal collection by subject in Portuguese and obtaining canonical page paths for later reading with ler_pagina. However, it does not explicitly state when not to use it or mention alternatives such as buscar_semantico, leaving some selection inference to the agent.

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 tool is known to be side-effect-free. The description adds the semantic mechanism (vector embedding, cosine similarity) and the fact that it returns page paths, which enriches the behavioral model without contradicting the annotations. It does not detail pagination or rate limits, but these are schema-managed.

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 sentences, tightly packed with essential information: the core operation, the distinguishing characteristic, the usage trigger, and the output's purpose. There is no redundant language, and the main purpose is front-loaded.

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 tool's moderate complexity, an output schema exists (though not shown), and annotations cover safety, the description covers purpose, usage, and downstream action. It omits niche details like error cases or performance, but nothing critical for an agent to invoke it correctly is missing. A small gap is not explicitly mentioning how the 'limite' interacts with returns, but the schema handles that.

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 schema already provides clear descriptions for all three parameters (pergunta, area, limite). The description does not add parameter-level guidance beyond the schema; it briefly reinforces that 'pergunta' is a natural-language question but no new information. Thus the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Busca') and resource ('páginas do acervo') and clearly contrasts with the lexical sibling 'buscar_paginas' by emphasizing semantic vs. lexical matching. It also names the downstream consumer 'ler_pagina', making the tool's role unambiguous.

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 explicitly states when to use it: when lexical search ('buscar_paginas') fails due to vocabulary mismatch. It also indicates that the returned paths feed into 'ler_pagina', providing a clear usage flow. This is direct and actionable for an agent.

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?

A descrição adiciona valor além da anotação readOnlyHint ao deixar explícito que nada é gerado sinteticamente: cada bloco reflete o que a página publicada afirma e inclui URL para conferência. Isso esclarece o comportamento de grounding e verificabilidade, um contexto relevante não presente nas anotações.

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 descrição é densa mas bem organizada: começa com o propósito, usa dois-pontos para listar componentes do contexto e encerra com uma ressalva comportamental importante. Todos os elementos contribuem para o entendimento, sem repetir o 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?

Para uma ferramenta de complexidade moderada, a descrição cobre bem os componentes da saída e o comportamento de não geração. Como há output schema disponível, não é necessário detalhar a estrutura de retorno. Faltam apenas orientações mais explícitas sobre quando usar versus alternativas.

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?

A cobertura do schema é 100%, então a linha de base é 3. A descrição não acrescenta detalhes novos sobre os parâmetros area, paginas ou pergunta além do que o schema já documenta; ela apenas menciona 'pergunta' de forma genérica.

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?

A descrição usa verbo específico e recurso claro: 'Monta o contexto jurídico denso para uma pergunta', e detalha o que compõe esse contexto (teses, dispositivos legais, precedentes, fontes, citações). Também diferencia o tool de ferramentas de geração ao afirmar 'Nada é gerado', o que o distingue de irmãos como 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?

Há contexto implícito de uso: a ferramenta serve para montar contexto jurídico denso a partir de uma pergunta e combinar buscas semântica e lexical. Porém, não há orientação explícita sobre quando preferir esta ferramenta a alternativas como search, buscar_paginas ou responder_pergunta.

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 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?

Annotations mark the tool as readOnlyHint=true, and the description reinforces this by framing the operation as returning a document. It adds useful behavioral context: the output is the same Markdown document served at a known URL, includes all published answers, and each answer contains author, verified OAB registration, and official sources. No contradiction with 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 a single compact sentence that front-loads the action and resource, then adds a clarifying path equivalence and content details. Every clause carries useful information 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 single-parameter, read-only tool with an output schema, the description adequately covers what is returned, the Markdown format, the content scope, and how the parameter relates to buscar_duvidas. Nothing essential for invoking it correctly 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 'duvida' accepts a slug or the full path returned by buscar_duvidas, with an example. The tool description adds no new parameter-level meaning beyond referencing the same served path, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource: it 'Devolve' (returns) 'uma dúvida da rede social' with all published answers in Markdown. It also identifies the exact served document at /redesocial/duvida/{slug}/index.md, which distinguishes it from sibling search/browse tools. It does not explicitly name a differentiating sibling, but the intended resource is 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?

The description implies the tool is for retrieving a specific dúvida with its full set of answers, and the schema adds that the slug can be the full path returned by buscar_duvidas. It offers clear context for when to use it, but does not explicitly state when not to use it or how it compares to alternatives like ler_pagina or fetch.

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 readOnlyHint annotation already covers safety, and the description adds meaningful context by specifying output format (Markdown) and contents (sections, FAQ, official sources with URLs). It also explains the purpose of sources for verification. There is no contradiction with annotations, and the description exceeds baseline by providing these details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that efficiently communicates the tool's action, resource, and output components. It is concise with no filler words, fully earning 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?

Given the tool's simplicity (one parameter, output schema present), the description is complete. It explains what the returned page contains and even how to use the sources for verification, which complements the structured output schema and provides enough context for a 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?

The schema already provides full coverage (100%) for the 'caminho' parameter with a clear description ('rota canônica devolvida pela busca, com barra final'). The tool description adds no additional parameter semantics beyond the schema, so the baseline of 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 is specific and action-oriented: 'Lê uma página do acervo em Markdown' clearly states the verb and resource. It enumerates content components (sections, FAQ, official sources) and implicitly differentiates from the sibling search tool 'buscar_paginas' by focusing on reading a specific page.

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 context is provided through the parameter description mentioning 'rota canônica devolvida pela busca', which implies this tool is used after a search to fetch a page. The description also hints at verification purposes ('é por elas que se confere o que a página afirma'), but it does not explicitly state when not to use it or contrast with 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?

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?

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?

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.