obter_dispositivo

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

With no annotations, the description carries the full burden and does so well: it discloses the delimiter wrapping of official documents as data-not-instruction (a prompt-injection defense), the four-valued status taxonomy with an explicit clarification that 'indisponivel' means capture or source failure rather than inexistence, and the returned url/capture_id used for citation. These are non-obvious behavioral traits an agent could not infer otherwise.

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 purpose, then inputs, then status semantics, then workflow ordering — no filler sentences. It is denser than ideal, packing parentheticals and a status enum into a short block, but every element 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?

Covers purpose, inputs, failure modes and citation outputs for a read-only lookup tool with no annotations; the output schema covers the return shape. Remaining gaps are minor: no guidance on handling 'ambigua' results (e.g., disambiguate and retry) or on auth/rate 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?

Schema coverage is 0%, so the description must compensate; it explains that `citacao` or the pair `work_id` + `caminho` must be supplied, and that `data` selects the redaction/version. It does not specify the expected syntax of `caminho` (a path within the work) or of `citacao`, nor what a null `data` means, so format-level meaning is still missing.

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 (obter) and resource (texto do dispositivo: artigo, inciso, parágrafo) plus the version dimension (na redação da `data`), which distinguishes it from siblings like historico_dispositivo and verificar_texto. The function is unmistakable 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?

Explicitly places the tool in a pipeline: 'Use depois de resolver_citacao ou buscar_legislacao e antes de citar o texto', naming the prerequisite siblings and the follow-on action. It also gives the input-mode alternatives (informe `citacao` ou `work_id` + `caminho`) and the status semantics that tell the agent whether to retry (indisponivel) or conclude non-existence (inexistente).

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