cite_child_link

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

Annotations declare write/non-idempotent/non-destructive, and the description adds genuinely beyond them: it explains that a ChildRef citation asserts BOTH sides of the link, and that reusing a citation handle causes the link to inherit a confidence 'its evidence never earned.' This is real semantic context about the object created.

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?

Front-loaded with the core action, then justification, then the single-parent caveat. The confidence-inheritance sentence is long but earns its place by explaining the rationale for not reusing a handle. No redundant restatement of the name.

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?

For a 3-param mutation tool with annotations and no output schema, the description covers the essential caveats: what the citation asserts, why not to reuse a handle, and the single-parent edge case. Nothing critical is missing for correct invocation.

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 meaning on top: the citation parameter is 'the PARENTAGE claim,' and it warns to create a new citation rather than reuse a handle, which sharpens how the citation param should be populated beyond the schema's own precedence text.

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 and resource: 'Cite the parent-child link itself, on the family's ChildRef.' It sharply distinguishes this claim ('child belongs to these parents') from the adjacent claim ('child appears in this record'), so an agent grasps the target object. It stops short of naming any sibling tool (e.g., add_child_to_family, cite_object), so sibling routing is inferred rather than explicit.

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?

Gives clear when-not guidance: do not reuse the child's existing citation handle, and 'Where only one parent is evidenced, cite that parent's relationship instead of implying both.' That routes the agent away from a wrong call. It never names an alternative tool to use in those cases, so it is implicit routing rather than explicit tool selection.

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