sage_messages_receive

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

With no annotation safety or read/write hints, the description carries the full burden. It discloses atomicity, token replay behavior, signing of one exact read acknowledgement, authoritative sender_agent field, and the important caveat that labels are non-authorizing metadata. This goes far beyond a superficial 'receives messages' description.

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 densely packs many important details, but it becomes a lengthy technical paragraph with winding clauses like 'legacy rows use the current display-name compatibility fallback for a missing saved registered name.' Every sentence contributes valuable information, but the phrasing is complex and harder to quickly parse than necessary.

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 lack of an output schema, the description goes a long way: it explains the returned message mechanics (authoritative sender, optional labels), replay semantics, and session/handoff behavior. It does not mention error cases, token expiration, or what happens if the token is reused after successful acknowledgment, but within the complexity of a receive/claim tool it is nearly complete.

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 covers receive_token with a basic descriptor and limit with constraints but no prose. The description adds substantial semantic value by explaining receive_token's replay behavior and semantic nuance. Limit is only loosely implied by 'bounded batch,' but the name and schema constraints make its role reasonably clear. This could be stronger for limit examples, but overall it meaningfully enriches the primary parameter.

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 uses a specific verb and resource: 'Receive and atomically claim one bounded local message batch.' It explains the core purpose (receiving/claiming messages) and includes distinctive semantics (replay with the same token, never claiming later messages) that clearly delineate what the tool does while differentiating it from generic receive tools.

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 concrete usage context: reusing receive_token replays the original lost response, and concurrent runtimes should use sage_message_handoff for transferring ownership. This indicates when and how to use the tool in special situations, but it does not explicitly say 'when not to use' or compare directly to alternative receive-like siblings.

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