Speakable thread digest

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

With no annotations, the description carries the full burden. It transparently discloses that markdown/code is stripped and lists what the digest contains. However, it does not explicitly state that the operation is read-only or describe any side effects, error behavior, or permission requirements. The read-only nature is implied by 'digest' but not stated, leaving a gap.

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?

Two sentences, no filler, front-loaded with the core purpose. The first sentence defines the output and contents, the second adds the target use case. Every word earns its place.

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 read-only tool with no output schema, the description provides a good picture of the returned content (thread status, last agent message, pending items) and the TTS focus. However, it omits how maxReplyChars affects the result and doesn't explicitly confirm read-only behavior, so it is not fully 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?

The description does not explain the parameters. threadId is implicitly 'one thread' but not explicitly described, and maxReplyChars is not mentioned at all. Schema coverage is only 50% (threadId has no description; maxReplyChars has only 'Default 800'), and the description fails to compensate by clarifying what maxReplyChars controls (e.g., output length for TTS) or how it affects the digest.

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 states the tool's purpose: producing a TTS-friendly plain-language digest of a thread, including what it's doing, the agent's last message (with markdown/code stripped), and pending items. It differentiates from siblings like get_thread (raw thread) and thread_status (status-only) by emphasizing the digest format and read-aloud design.

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 clear context: 'Designed to be read aloud by a voice assistant' and 'TTS-friendly' indicate that this is for spoken consumption. It implies usage when a summarized, speech-optimized version is needed, but it does not explicitly state exclusions or name alternative tools. This matches 'clear context, no exclusions'.

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