mind_skill

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

With no annotations provided, the description carries the full burden and does substantial work: it discloses that name is the identity so re-writing the same name edits in place and preserves history, that remove deletes, and that verify=true should only be used for deterministic signals, 'never a hunch.' It also explains that match ranks by relevance and by observed outcomes. Not covered: what match/list/show actually return or any error/permission behavior.

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?

A single dense paragraph, front-loaded with the core concept and the sibling contrast before detailing actions; nearly every clause conveys a distinct rule. Slightly breathy in places ('the way you would check for a house rule'), and the action list reads as a run-on, but nothing is gratuitous.

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 six-action tool with eight parameters and no output schema, the description explains the semantics of each action but never describes what match, list, or show return (ranked playbooks with what fields? the body? history?). Mutation-side behavior is well covered, but the read-path gap leaves an agent guessing about results.

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 already 100%, so the baseline is 3, but the description adds real meaning beyond the schema: name-as-identity semantics (writing the same name edits and keeps history) and the constraint that verify should only be set on deterministic signals. The 8KB body cap and task/when roles 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?

The description names the resource concretely (skills/playbooks, 'the house way of doing a kind of work') and its trigger (the task you are about to start), which is enough to separate it from mind_recall_all/mind_recall. The multi-action surface (match/set/list/show/remove/outcome) is enumerated, though the primary verb is diffused across six operations rather than stated crisply up front.

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 states when to call it ('before starting non-trivial work'), what action to use for the common case (action=match takes a task description and returns the playbooks that apply), and explicitly routes the agent away from the sibling: 'mind_recall is the other half: it answers an error that already happened.' Per-action guidance is bundled in as well.

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