aguardar_resposta_chat_cap1g

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

Annotations indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the tool is safe and idempotent. The description adds the block/wait behavior and the concept of 'timeout', which is beyond annotations. However, it doesn't disclose what happens on timeout (error? empty result?), nor it explains the 'desde_id' semantics in the context of blocking behavior. No contradictions.

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, short sentence that is front-loaded with the core action (espera mensagem nova) and the key condition (desde a última entregue). It is concise, though it omits necessary details, but structure is clean.

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 is a blocking wait operation with three parameters, but the description lacks critical information such as return value, timeout behavior, and how 'desde_id' is used. While an output schema exists, the description doesn't clarify what triggers the return (new message vs state change) or what the return object contains. An agent would need to infer too much.

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%, so the description must clarify each parameter, but it fails to do so. It doesn't explain what 'referencia_chat' refers to (chat ID?), what 'desde_id' means (last message ID?), or how 'timeout_segundos' affects the call. The description only mentions 'tempo dado' which hints at timeout but doesn't tie it to the parameter clearly.

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 the core function: waiting for a new message or state change until a timeout. However, it is vague about what the tool returns (the message? the state change?) and how it relates to the chat lifecycle. It is distinguishable from siblings like 'enviar_mensagem_chat_cap1g' and 'ler_chat_cap1g' but does not clearly differentiate itself, e.g., it could be confused with 'verificar_chat_cap1g' which might also check for updates.

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 usage: call this after sending a message and when expecting a response, and it waits for a new message or state change. However, it does not explicitly say when to use it versus 'ler_chat_cap1g' or 'verificar_chat_cap1g', nor does it mention any prerequisites like needing an active chat session (which likely exists given sibling tools like 'iniciar_chat_cap1g').

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