needfix_add

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

No annotations exist, and the description carries real weight: dedupe behavior is stated concretely ('the existing row is returned, nothing new is written' with existing_id), kind synonyms are said to be normalized server-side with the exact mapping given, and status is noted as governed by lifecycle and manager authority. What is missing is error/permission failure behavior and validation constraints.

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 lead sentence is front-loaded and the receipt block at the end is well placed. Some space is spent restating schema enums verbatim (the severity list especially), although the kind synonym mapping and the status authority note are new information that justifies their length.

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?

There is no output schema, and the description compensates well by describing the needfix_add_receipt.v1 fields and the dedupe outcome. However, a 14-parameter write tool with mostly undocumented optional inputs (evidence, caused_by, provenance, scope_*) leaves the agent guessing about what structured context to attach.

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 only 21% across 14 parameters, so the description must compensate. It does well for kind (enum plus synonym mapping), severity (full enum), and status (enum plus default and gating note), but tags, scope, scope_files, scope_symbols, evidence, evidence_refs, caused_by, provenance, and readiness_score get no explanation at all in either place.

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 opening sentence gives a specific verb, resource, and authority level: 'Manager-authority add of a NeedFix (dedupe-aware).' That is enough to separate it from needfix_update, needfix_convert, and dashboard capture variants by function. It stops short of naming a sibling it must not be confused with.

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 'manager-authority' framing and 'dedupe-aware' note imply that callers need manager rights and that repeats short-circuit, which is real usage context. But there is no explicit when-to-use/when-not or routing to alternatives such as needfix_preview_convert or needfix_draft, so the agent must infer placement among the many needfix_* siblings.

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