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

Annotations already declare readOnlyHint=true, so safety is covered by structured data. The description adds genuine behavioral context by stating it includes both your in-progress work and actions others took on your work while away, which is useful for framing expectations, but it discloses nothing about volume, scoping, auth, or whether the window is bounded.

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 short sentences with no filler, and the action directive ("Call first on return") is front-loaded at the end where it reads clearly. It is economical, though the evocative phrasing sacrifices some precision that a slightly more literal clause could have preserved.

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 three-parameter tool with no output schema, the description is thin: it never explains what brief or detail do, nor the shape or extent of what is returned. It gives enough to know the general intent but leaves the agent relying on schema fields it does not reinforce.

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?

With 67% schema coverage, brief and since are documented in the schema while detail has no description anywhere. The description contributes no parameter-level meaning at all (no mention of brief, since, or detail), so it neither compensates for the gap nor adds beyond the schema. A baseline 3 is appropriate.

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 conveys what the tool surfaces (what you were in the middle of, plus what others did while you were away), but it does so in abstract, atmospheric language with no explicit verb and no differentiation from siblings like observe, inbox, or due that could plausibly return similar state. An agent can infer it is a re-orientation read, but the resource boundary is fuzzy.

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?

"Call first on return" is a clear, actionable when-to-use condition that positions this as the entry-point call after time away. It stops short of naming alternatives to avoid (e.g., inbox, observe) or when it should be skipped, so it lacks explicit exclusions, but the usage trigger itself is unambiguous.

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