read_chat

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

With no annotations, the description carries the full burden of behavioral disclosure. It does disclose important behavior: messages are returned since the last read or since an explicit since_id, and the caller's own lines are excluded. However, it does not clarify whether reading advances the server-side 'last read' cursor, whether there is pagination, or whether any authentication or stateful side effects apply.

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 compact sentence that front-loads the core behavior and adds the key scope exclusions efficiently. Every phrase adds value; there is no filler or redundant restating of the tool name.

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 simple one-parameter read operation with an output schema present, the description covers the main facts an agent needs: what is returned, the cursor semantics, and whose messages are included. The only notable gap is the unclear side effect on the 'last read' marker, which matters for repeated polling but does not greatly reduce usability.

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 parameter documentation. The parenthetical 'or since since_id' does explain the parameter's role, and the parameter name plus schema type are fairly self-explanatory. However, the description does not clarify the distinction between null (use last-read cursor) and an integer (use explicit position), leaving some work to the agent.

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 identifies the resource (chat messages) and the operation's scope: messages since a cursor, from players and other agents, excluding the caller's own lines. It is not fully a verb+resource phrasing ('Chat messages since...' rather than 'Read chat messages...'), but the title disambiguates the action. It implicitly distinguishes from 'say' by focusing on reading and excluding own lines.

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 gives no explicit guidance on when to use this tool versus alternatives like 'say' or 'get_events'. It describes the behavior but not the context or conditions under which an agent should call it. There is no mention of when not to use it or what makes it the right choice.

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