feedback_resolve

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

Goes well beyond the annotations: it discloses that buddie re-runs the chain's own check options, names the judging criteria (scope, no added lines except 'buddie:' disclosures, verified claims kept), states the decision is appended to the chain, and specifies atomicity ('a refused submission changes nothing'). Minor gap: idempotencyHint=false is not explained, and openWorld behavior isn't elaborated.

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?

Three sentences, front-loaded with the core action, then validation detail, then return/refusal behavior. Dense but each clause carries information; slightly clunky phrasing but no 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?

No output schema, but the description explains what is returned (the decision and next feedback) and the refusal case. For a mutation tool with full schema coverage and annotations, this is largely complete; only the shape of the 'decision' and handling of specific refusal codes remain implicit.

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 chain/feedback/submission/original_text/corrected_text are already documented. The description adds a little meaning ('one corrected text' being checked against chain's check options) but does not clarify the submission object fields or how original_text/corrected_text relate to the artifact hashes.

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?

States a specific verb+resource ('answer a chain's open feedback with one corrected text') and describes the internal validation and append step. It's clearly distinguishable from siblings like feedback_start/feedback_accept by its resolve-and-append role, though it never names those alternatives.

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?

Usage is implied: you call this to answer an open feedback-v1 returned by feedback_start. There is no explicit when-to-use statement, no contrast with feedback_accept, and no prerequisites (e.g. that an accepted/started chain must exist) spelled out.

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