mq_recv

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'receive and consume' and 'poll periodically,' which implies a read operation with potential side effects (consumption). However, it lacks details on critical behaviors: whether messages are deleted after consumption, authentication needs, rate limits, error handling, or what happens if no messages are available. This leaves significant gaps for an agent to understand the tool's 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 concise with two sentences that are front-loaded: the first states the core purpose, and the second adds behavioral context. There's no wasted text, and it's appropriately sized for the tool's complexity. However, it could be slightly more structured by explicitly separating purpose from usage.

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 (a message consumption tool with potential side effects), no annotations, no output schema, and 0% schema coverage, the description is incomplete. It lacks details on parameters, return values, error conditions, and full behavioral traits. The description alone doesn't provide enough context for an agent to use the tool effectively without guessing.

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 compensate for undocumented parameters. It doesn't mention any parameters or their semantics. The two parameters ('name' and 'msg_type') are entirely unexplained in the description, failing to add meaning beyond the bare schema. This is inadequate given the low coverage.

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's purpose with specific verbs ('receive and consume messages') and identifies the resource ('for an agent'). It distinguishes from siblings like mq_send (sending) and mq_history (viewing history), though it doesn't explicitly name alternatives. The purpose is specific but could be more precise about what distinguishes it from mq_ls or mq_add.

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 implied usage guidance by mentioning 'poll periodically to check for new messages,' which suggests when to use this tool (for ongoing message consumption). However, it doesn't explicitly state when to use this vs. alternatives like mq_history for past messages or mq_send for sending. No exclusions or prerequisites are mentioned, leaving gaps in guidance.

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