Chat Read

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

With no annotations, the description carries the full burden and delivers real behavioral detail: messages are returned newest-first bounded by limit/since, filtering to venue/user means only those, and records with ok=false were refused and are never shown. It omits what happens on empty results or errors, and doesn't confirm whether history is bounded in any other way.

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?

Purpose and ordering rule come first, then the record shape, then the usage and handoff — a sensible front-loaded order with no filler sentences. The 'kind said, with by and ok' fragment is dense shorthand that costs some readability but packs genuine information.

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 described, yet the description still sketches the record shape (kind/with/by/ok) helpfully. For a 4-parameter read tool it covers scope, ordering, filtering, and the follow-up workflow; only edge-case behavior (empty history, since out of range) is unaddressed.

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 coverage is 0%, so the description must compensate, and it does address all four parameters: limit (newest N lines), since (a position after which to read, clarified by 'since=<its last>' implying a last-seen position), and venue/user (restrict to only those). The venue/user phrasing is terse and it never clarifies that since is an integer line index rather than a timestamp, so the compensation is good but not complete.

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?

States a specific verb and resource ('Chat history from the log') plus the exact ordering and scope rule ('newest limit lines after since'). It goes further by naming the sibling chat_watch and differentiating the read-from-log role from the live-watch role, so an agent can tell them apart without opening either schema.

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?

Gives two concrete use cases ('catch up after a gap', 'see what was already answered') and an explicit follow-up handoff: chat_watch(who, since=<its last>) so nothing is answered twice. The only gap is that it never states an explicit 'do not use this when...' exclusion; the live-vs-history split is only implied by the handoff.

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