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

Annotations already establish read-only, non-destructive, closed-world behavior. The description adds genuinely non-obvious traits: transient processing, consent gating, PHI exclusion, and the deliberate framing of suspected patterns as questions rather than causes. It does not, however, describe what the user gets back (deferred to the output schema) or anything about retention beyond 'transient'.

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, no filler, with the output framing front-loaded and the safety constraints following. 'Structures' is the one slightly abstract word, but the rest of the sentence pins it down, so the density is earned.

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 spelled out. For a 5-parameter health-reflection tool the description covers the safety posture, scope boundary, and output framing, which is most of what an agent needs. Remaining gap is the precise role of possiblePatterns and any statefulness across calls.

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 only 20%, so the description must carry weight here. It maps cleanly onto baselineBefore/during/recoveryAfter via 'before, during and recovery observations' and reinforces the consentConfirmed gate, but 'possiblePatterns' is left unexplained beyond a hint in 'presenting suspected patterns as questions,' and item-level constraints (25 items, 1000 chars) are schema-only.

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 concrete verb and resource: it structures before/during/recovery observations and reframes suspected patterns as questions. That is specific enough to distinguish it from build_health_timeline (raw timeline assembly) and find_symptom_words (vocabulary lookup). It stops short of explicitly naming a sibling, so it does not reach a 5.

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 supplies hard preconditions (explicit consent, transient processing, PHI out of scope) which is more than generic guidance, but it never says when to reach for this tool versus prepare_appointment_brief or build_health_timeline. Usage is implied by the phase-based inputs rather than stated.

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