Record an assessment of related work

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

Annotations are minimal (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description carries the burden and meets it: append semantics ('Each call appends a new assessment rather than replacing an earlier one'), non-mutation of statuses ('changes no statuses: it does not open, resolve or dismiss conflicts'), an ownership check, and the return shape ('Returns the stored assessment with its asm_ id'). These behaviors go well beyond what the annotation flags convey and do not contradict them.

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?

Seven sentences, each earning its place: purpose, verdict semantics, timing, side-effect disclosure, follow-up routing, ownership, and return value. The purpose is front-loaded in the first sentence, followed by the workflow constraint. There is no filler, no repetition of schema text, and the level of detail is proportionate to the tool's 6-parameter workflow complexity.

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?

Despite having no output schema, the description discloses the return value ('Returns the stored assessment with its asm_ id'). It covers the full call envelope: when to call, how often, what side effects occur (appended, no status changes), who may call (owner only), and what to do next. For a 6-required-parameter workflow tool with two enums, this is complete enough for an agent to select and invoke it correctly.

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 100%, so the baseline is 3. The description adds workflow meaning the schema cannot: 'deciding what that means is yours' tells the agent the verd_ict parameter is a judgment call on foremerge's overlap data, and 'Act on the verdict with coordinate_with_agent, resolve_conflict or discard_work' explains the intent of the action enum. It doesn't redundantly restate parameter docs, only enriches them, justifying a point above baseline.

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 states a specific verb and resource: 'Record what you concluded about one entry from related_work.' It distinguishes itself from siblings by explicitly framing what it is not: 'it does not open, resolve or dismiss conflicts,' and by routing follow-up action to coordinate_with_agent, resolve_conflict, and discard_work. An agent can tell it apart from publish_intent, check_conflicts, and resolve_conflict without opening their schemas.

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?

Timing is explicit: 'Call this once per related intent, after publish_intent and before you write code.' Ownership is stated as a precondition: 'Only the intent's owner may assess it.' Alternative routing is named directly: 'Act on the verdict with coordinate_with_agent, resolve_conflict or discard_work as needed.' Nothing about when to invoke this tool is left to inference.

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