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

The description discloses a real behavioral trait: it 'Returns new ones (marks them read).' However, that side effect directly conflicts with the supplied readOnlyHint=true annotation, which promises no state modification. An agent relying on the annotation could call this assuming it is side-effect free and unexpectedly consume the unread queue.

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?

Three short sentences, each doing distinct work: what it returns, the read-marking side effect, when to call it, and how to widen scope. Nothing is padded and the core purpose is front-loaded.

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 one-parameter, no-output-schema tool, the description covers purpose, trigger conditions, scope control, and the read-state side effect, which is enough to call it correctly. The remaining gap is the unaddressed tension between the mutation side effect and the read-only annotation, leaving the agent unsure which to trust.

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 schema already documents the single boolean at 100% coverage ('Include ones already read'), so the baseline is 3. The description adds usable meaning by framing all:true as 'the recent history,' which tells the agent the flag's purpose rather than just its mechanical effect.

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 uses a concrete verb-and-resource framing: it returns 'instructions and notes your person left for you by calling or texting their own line.' That is a clear statement of what the tool fetches and where the content originates. It doesn't explicitly contrast with siblings like my_calls, transcript, or notes, so an agent must infer the boundary itself.

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?

It gives explicit triggering conditions: 'Check this when you start work and whenever they say they phoned something in.' That is unusually actionable usage guidance. It lacks a when-not or a named alternative for overlapping needs such as call transcripts, so it stops short of a 5.

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