research_capture_document_chunk

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine behavioral value by stating what is persisted (source location and file hash) and that it deliberately does not validate the source text. It omits idempotency (what happens when the same chunk is registered twice) and error behavior.

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?

A single tight sentence with three meaningful clauses: the action, what is retained, and the non-validation caveat. Nothing is padded or repeated, and purpose is front-loaded. It is arguably too terse for a 4-required-parameter mutation tool, which costs it a point.

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?

A mutation tool with four required ID-style parameters, no output schema, and no schema descriptions needs the description to explain the identifier roles and the return/registration outcome. The description covers neither, and leaves open whether duplicate registration is possible. What it does say is accurate but far from sufficient.

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 4 required parameters, so the description carries the burden and fails to meet it. It mentions neither study_id, document_id, chunk_id nor title, and does not explain the ID format conventions (r_/d_/chunk_ prefixes). 'Preserves source position and file hash' does not map to any input parameter, so nothing compensates for the coverage gap.

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 verb+resource: registering a selected document chunk as citable evidence. It is clearly a capture/registration operation, distinct from read tools like research_document_chunks or research_get. However, it never differentiates itself from the closest siblings, research_add_evidence and research_capture_node, so an agent still has to guess which capture path applies.

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 rather than stated: the chunk must already be 'selected' and the tool turns it into citable evidence. The caveat '不验证原文真实性' hints that verification is a separate step, but no sibling (research_add_evidence, research_record_verification) is named as the alternative, and no exclusions or prerequisites are given.

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