read_session

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

Annotations already declare readOnly, non-destructive, closed-world and idempotent, so the safety profile is covered; the description's contribution is the cursor-like behaviour (only output produced since the previous read). That is genuinely useful context, but it omits blocking/timeout semantics and what happens when the session has ended. There is also a latent tension worth surfacing: a cursor-advancing read is not strictly idempotent, which sits awkwardly with idempotentHint=true.

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?

A single short sentence with no filler, which is good, but here brevity costs clarity: the fragment lacks a verb and front-loads an adjective phrase rather than the action. It is under-specified rather than efficiently concise.

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?

An output schema exists, so return values need not be explained, but the description still leaves critical gaps for a stateful polling tool: the meaning of 'wait', whether the call blocks, session lifecycle prerequisites, and behaviour on an exhausted or terminated session. For a two-parameter streaming-read tool it does too little of the work.

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% for both parameters, so the description must compensate and largely fails. It implies that session_id refers to a session but says nothing about its form, and the 'wait' parameter — which looks like a poll/block duration defaulting to 2 — is completely unaddressed despite being the main source of invocation ambiguity.

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 fragment "New output of a session since the last read" conveys the resource (a session) and the incremental-read semantics, but never states a verb and reads as a noun phrase. It does implicitly distinguish itself from start_session/stop_session/list_sessions by signalling delta-reading, yet the phrasing is ambiguous enough that an agent could misread it as fetching session metadata.

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?

There is no explicit when-to-use guidance, no statement of prerequisites (must a session be started first?), and no routing against the many siblings such as list_sessions or tail_log. The only usage signal is the implied "call this repeatedly to poll for new output", which the agent must infer.

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