candidate_reference_read

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

With no annotations, the description carries the full burden. It discloses meaningful behavior: fresh-read semantics tied to an injected card version, and an instruction to stop reading old versions when status or source changes. But it says nothing about permissions, auth needs, what happens on expected_version mismatch, or the return shape.

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 uses two dense sentences, starting with the purpose and scope, then the pagination/staleness rule. There is no filler, though the phrasing is terse enough that the pagination mechanics remain opaque.

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?

The tool is a 6-parameter reader with no annotations and no output schema, so the description must explain the response. It never says what a read returns, how 'section' affects the result, or how a version mismatch is signaled, which leaves an agent unable to call it correctly beyond required fields.

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?

There are 6 parameters with 0% schema description coverage, so the description must compensate, and it only partially does. '按注入卡的版本分页' hints at expected_version and offset, but the 'section' enum (content/applicability/limitations/evidence), max_chars, context_handle, and candidate_id semantics are entirely undocumented.

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?

It uses a specific verb and resource: '读取已允许参考的未发布候选' (read unpublished candidates allowed for reference). It also explicitly states what the tool is NOT ('不是验证结论或执行授权'), which helps separate read access from validation or authorization tools. It does not name a sibling tool such as candidate_reference_feedback, so sibling separation relies on inference.

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?

It provides negative usage guidance ('不是验证结论或执行授权') and a stopping condition ('状态或来源变化时停止旧版读取'). That implies when to use the tool and when to stop, but it never says when to choose a sibling, such as candidate_reference_feedback or knowledge_read, instead. Usage is implied, not stated.

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