candidate_reference_feedback

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

With no annotations at all, the description usefully discloses that this is 'reported' feedback that does not prove disproof, and that it will not publish or retry administrators – real side-effect and semantics context. However, it omits that the operation is version-guarded (expected_version is required, 64 chars), idempotency-keyed, and whether the pause is reversible, all of which matter for a mutation.

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?

It is short and front-loads the trigger plus the effect, but the telegraphic clause chain ('不证明已证伪，不发布或重试管理员') packs three distinct disclosures into one undifferentiated run, making it harder to parse than a two-sentence split would be.

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?

Against a mutation tool with 8 undescribed parameters, no annotations, and no output schema, the description covers only the high-level meaning of the action. It leaves required versioning and idempotency behavior, the expected return, and error conditions entirely undocumented.

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 description coverage is 0% across 8 parameters, four of them required, so the description should compensate and does not. It explains nothing about candidate_id, summary, expected_version (optimistic concurrency), idempotency_key, or the optional event_refs/context_handle/expected_task_* fields; only candidate_id is indirectly implied by the subject of the sentence.

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 concrete action and effect: pausing automatic reference for a candidate whose report flagged it as inapplicable or questionable. The verb ('暂停其自动参考') and resource ('候选') are identifiable, and it is distinguishable from the read-only sibling candidate_reference_read, though the framing clause '报告已展示…' is roundabout.

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 trigger condition is implied – use this when a report shows the candidate is inapplicable or questionable – but no alternative is named, and the sibling list contains candidate_reference_read and case_feedback, so the routing between recording feedback versus reading references versus case-level feedback 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.