list_executions

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description still earns credit for adding behavior not in annotations: results are returned most-recent-first, and trace_id performs a correlation lookup on the integrator-supplied metadata.trace_id rather than a native id. It does not describe the response payload or total-count behavior, which keeps this from a 5.

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?

It is front-loaded with core purpose, then routing, then parameter conventions, one idea per sentence with no filler. The embedded enumeration of source values is somewhat redundant with the schema but is short enough not to bloat the 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?

For a 9-parameter, all-optional read-only list tool with no output schema and full annotation coverage, an agent has enough to call it correctly: filters, paging defaults, date format, ordering, and where to go for details. The only real omission is any hint of what the returned execution records contain.

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?

At 67% schema description coverage the schema already carries most parameter meaning, and much of the description repeats it: the source list (chat, sse, mcp_server, webhook, schedule, email, task, builder, process) and the trace_id/metadata.trace_id mapping both appear in the schema descriptions too. Genuine additions are limited to the ISO 8601 date convention and the endpoint analogue (GET /api/v1/executions). status, agent_id and session_id gain nothing here.

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?

"Busca execuções de agentes do tenant (mais recentes primeiro) com filtros e paginação" names a specific verb, resource, scope and default ordering, and immediately delegates detail/trace work to named siblings, so an agent can distinguish it from get_execution_diagnostics and get_execution_trace without opening a 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?

It explicitly routes adjacent use cases: "Para o detalhe de uma execução: get_execution_diagnostics; para a árvore multi-agente: get_execution_trace." That is clear alternative selection. It stops short of 5 because it does not address the other overlapping list tools in the sibling set (list_trigger_executions, list_agent_history, list_consumer_sessions).

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