senado_processo_detalhe

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating safe, idempotent reading. The description adds value by specifying the return structure ('{ secao, count, total, aviso?, itens }'), limit behavior (default 100, max 500), and raw API records for prazos. No contradictions with 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 a single paragraph but well-organized: main purpose first, then each section with its fields and filters, common parameters, return format, and prerequisite references. It is front-loaded and efficient, though slightly dense. Minor room for brevity, but every sentence adds value.

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 complexity (10 parameters, 3 sections, multiple conditional filters) and that an output schema exists, the description covers all essential aspects: purpose, each secao's fields and accepted filters, return structure, limit, and prerequisites. It does not explain field semantics in depth, but the output schema likely covers that. Complete for the tool's needs.

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%, but the description adds significant meaning beyond the schema: it explains each secao's specific fields (e.g., emendas returns id, identificacao, etc.), optional filters per section (e.g., codigoParlamentarAutor for emendas), and date format (YYYYMMDD or ISO). This enriches the schema descriptions and helps select correct parameters.

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 details aspects of legislative processes ('Detalha um aspecto de processos legislativos') based on the 'secao' parameter, listing three specific sections (emendas, relatorias, prazos) with detailed fields. It distinguishes itself from siblings like senado_obter_processo (general process info) and senado_search_processos (search) by focusing on detailed sub-aspects.

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 explicit guidance: it tells users to obtain 'idProcesso' via 'senado_search_processos' and use 'senado_tabelas_processo' for prazo types. It states at least one filter is required and explains which filters apply per section. While it doesn't explicitly say when not to use it, the context implies it's for detailed aspect queries, effectively differentiating from sibling tools.

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