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

Annotations only declare non-read-only, idempotent, non-destructive; the description adds the real behavioral burden: omitted fields stay, null deletes, supplement on a populated field raises PROFILE_MERGE_REQUIRED and is atomic (nothing saved), retry must switch to compiled, no server LLM or pending queue, and no-ops don't bump version. That is far beyond what the annotations convey.

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?

It is front-loaded with the core mode distinction and every clause carries operational information, but the telegraphic semicolon-chained style packs several rules per sentence and makes it harder to scan than it needs to be. Length is reasonable for the complexity; readability is the cost.

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 versioned, atomic mutation tool with no output schema, it covers merge semantics, error path, idempotency, size limits, and evidence rules. It stops short of describing the success response shape or the full error taxonomy beyond PROFILE_MERGE_REQUIRED, which leaves a small gap for an agent handling failures.

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 carry everything, and it largely does: mode semantics, resume gating, request_id as an idempotency token, expected_version implied by conflict/re-read and version-bump rules, and patch value rules (<=500 chars, <=8 KB total) plus the meaning of the state enum values (user_reported, document_supported, needs_confirmation). Only minor gaps remain, such as the expected_version bump behavior on conflicting writes.

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?

'Save important career facts' plus the compiled/supplement mode distinction makes the verb and merge semantics clear, and 'Read first' implicitly points at get_profile. It never names a sibling explicitly, so an agent must infer the pairing with get_profile/delete_profile rather than being routed.

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 conditions for the key decisions: compiled vs supplement, 'Read first', 'batch meaningful changes', 'Reuse request_id for identical retry', 're-read on conflict', and a hard exclusion for resume=True ('only on explicit request to resume paused memory'). The when-not guidance ('no full chats/files/secrets', 'never reconstruct deleted facts') is equally specific.

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