mesh_read_inbox

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

Annotations are absent, so the description must carry the behavioral burden. The description does disclose important traits: it is 'Instant, a local SQLite read, never blocks' (non-blocking), which is key for agent decision-making. It also reveals that rooms only show messages from when the process was watching. However, it does not disclose the full return format or ordering details beyond the per-room limit, which is a minor gap given there is no output schema.

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 front-loads the core purpose and key details. Every sentence earns its place: reading content types, the pending-ring note, the always-readable nature, the parameter use, and the temporal scoping. It is not overly long given the behavioral transparency it provides without annotations.

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 tool's moderate complexity (multiple content types, optional filtering) and the absence of an output schema, the description covers what the agent needs: what to expect, how to filter, and the non-blocking nature. The only missing piece is a detailed return structure, but since there is no output schema, the description compensates well by listing content categories.

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 100% (both limit and room_topic have descriptions). The description adds a little extra meaning: it explains the purpose of room_topic ('Pass room_topic to read one room only') and implies the limit applies per room. However, most parameter details are already in the schema, so the description doesn't add substantial new semantics beyond usage context.

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 starts with 'Read what has arrived' and immediately enumerates the specific content types (rings, rooms, threads, broadcasts), making the tool's purpose unambiguous. It clearly distinguishes from siblings like mesh_get (generic retrieval) and mesh_lobby_transcript (lobby-specific), and names mesh_answer_ring explicitly for the pending-ring case.

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 on when to use this tool ('Read what has arrived') and even mentions a related action: if someone rang you under your 'ask' policy, use mesh_answer_ring. It also clarifies the optional room_topic parameter to read a single room, and contrasts with 'rooms only ever show what arrived while this process was watching them' – explaining the scope and limitations. This is sufficient for an agent to decide when to call it.

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