voicememos_voiceprint

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

With no annotations, the description must carry behavioral disclosure, and it does disclose meaningful traits: processing is local, the other-voice entry is 'never shown by name' (a privacy/semantics guarantee), and name defaults from config. It stops short of saying what enrollment persists, what each action returns, or how failures are reported — notable gaps for a state-mutating action set.

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 one-line purpose is front-loaded and the Args block is organized rather than rambling; every clause carries actionable detail. It is slightly verbose in the parentheticals ('e.g. a relative who sounds similar'), but no sentence is pure 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?

Six parameters, no annotations, and no output schema means the description is the only source of truth, and while parameters are fully explained, the return shape of 'status' and 'identify' is only hinted at ('enrollment state, thresholds and suggested enrollment memos'). An agent can invoke it correctly but cannot predict what comes back or what errors to expect.

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 does all the work, and all six parameters are documented with per-action scope: 'memos' means different things for enroll/identify/add_other, 'since'/'until' are restricted to 'identify' with a YYYY-MM-DD format, and 'name'/'speaker' are disambiguated by action. This is exactly the compensation a 0% coverage schema requires.

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 verb and resource: 'Recognise the owner's voice with a local voiceprint,' and the Args block enumerates five mutually exclusive actions, which frames the tool's full scope. It doesn't explicitly name or contrast with siblings (voicememos_transcribe, voicememos_second_read), but the voiceprint domain is distinctive enough that confusion is unlikely.

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?

Each action carries its own when-to-use condition: 'enroll' requires memos where only the owner speaks, 'identify' applies to already transcribed memos, 'add_other' exists specifically to prevent mistaking a similar-sounding relative for the owner. It even specifies data thresholds (2+ memos, ideally 4-6 from different years) and that 'speaker' is only needed for multi-speaker memos, leaving little to inference.

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