Learned preferences

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false. The description adds real context beyond that — preferences are injected at session start and apply immediately with no approval — which is the key behavioral trait an agent needs. It also states a hard constraint against storing secrets or private data. It does not describe what happens to existing entries when a rule is replaced or dropped, so depth is moderate.

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?

Front-loaded with the core identity before action and scope detail, and nearly every clause carries operational information. It runs long and mixes several concerns into single sentences (the learn action list is dense), but there is little true filler.

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?

With no output schema, the description covers what show returns (a list with ids) and covers the mutation model, scope levels, and content rules for learn. For a 3-parameter tool with one required enum, an agent has enough to invoke it correctly. Edge behavior on replace/drop of existing entries is the only notable omission.

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 67%, and the description fills the meaningful gaps: it defines what each learn action value means, explains scope as global vs org vs project, and instructs how to phrase the rule field ('general, short instruction, one step more general than the message'). That is genuine added meaning over the enum in the schema. The maxItems cap and id-on-forget detail are left to the schema.

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?

Opens with a specific framing — a learned preference store covering style, workflow, wording, tools — and enumerates the three actions (show/learn/forget) with what each does. An agent can tell this holds durable user preferences. It doesn't explicitly distinguish itself from sibling memory tools like save_memory, remember, or rules, which keeps it from 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?

Gives a concrete trigger: 'call learn when the user asks you to remember how they want something', and clarifies that in Claude Code the panel learns automatically. The learn sub-actions (new/reinforce/refine/replace/drop) each carry a plain-language condition. It stops short of telling the agent when to prefer this over save_memory or remember.

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