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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the description doesn't need to restate mutation. It adds substantial behavioral context beyond annotations: the confidence calibration ladder (0.95→0.20), the requirement for exactly three sampleQuestions in the user's voice, the tracker duplicate-name rejection behavior, the batch-write limits (100 items), and the 'receipts report each saved/failed item; do not claim all saved from a partial result' warning. It doesn't fully disclose all side effects (e.g., what happens on partial batch failure beyond receipts), but for a 49-param tool this is strong coverage.

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?

The description is long (roughly 500 words), but every sentence earns its place given the tool's 16 entityTypes and 49 parameters. It is front-loaded with the core purpose and the decision ladder, then progressively details each branch. The numbered ladder structure makes it scannable. It loses one point for density — the profile-block paragraph and the skill paragraph pack multiple rules into single sentences, which could be split for easier parsing — but it is not bloated or repetitive.

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 tool with 16 entityTypes, 49 parameters, nested objects, and no output schema, the description is remarkably complete. It covers the decision procedure (ladder), the data-quality requirements (confidence, sampleQuestions), the sibling routing (penny_edit, penny_delete), the batch semantics, and the project revision flow (expectedRevision, operationId). The only minor gap is that it doesn't describe the return shape, but with no output schema and the receipts warning, the agent has enough to call correctly. Nothing critical is missing.

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 description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the entityType ladder that determines which parameters are relevant, and by giving concrete examples for sampleQuestions ('What citation style should I use for the paper?'). It also clarifies semantic nuances the schema can't: 'A tracker name does NOT upsert (unlike skill)', 'profile blocks are upserts', and 'a note is the fallback, not the default'. It doesn't document every one of the 49 parameters, but the schema already does that; the description's job is to explain selection logic, which it does thoroughly.

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 opens with a vivid, specific verb phrase ('Save the moment something durable emerges') and immediately names the resource ('the user's memory'). It then enumerates the full entityType ladder with concrete examples (decision, preference, plan, correction, to-do, measurement), which distinguishes this write tool from siblings like penny_read and penny_edit. The 'first match wins' ladder is a clear decision procedure, not a vague restatement.

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 is explicit about when to use this tool vs alternatives: it says to use penny_edit for modifications, penny_delete for trashing, and names the profile-block upsert path. It gives conditional routing ('if no tracker fits, propose one before logging', 'when unsure between a note and the above, prefer the specific type'). It also states when NOT to save (pending_share_approval is a proposal, not a save). This is the strongest possible usage guidance.

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