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

Goes well beyond the annotations by disclosing a real side effect the agent could not infer: the document is promoted to the matching rules kind. It also adds same-tenant constraints and per-scope authorization requirements, which annotations do not cover. The idempotent claim duplicates the annotation, but everything else is additive.

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?

Five short sentences, front-loaded with the action and followed by the mechanics, permissions, and the sibling pointer. Nothing is redundant with the schema and no sentence is 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?

Covers action, side effect, authorization, tenant constraint, and a redirect for the adjacent operation, and an output schema exists so return values need not be described. An agent could invoke this correctly after one read.

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 value by packaging the call recipe ('scope=tenant|project|group, document_id, and (for project/group) owner_slug') into one line, making the conditional owner_slug requirement obvious at a glance. It does not mention tenant_slug or explain its multi-workspace behavior, which the schema carries alone.

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: 'Link an existing document as the rule doc for a scope', and immediately clarifies that this sets a link rather than editing content. The final sentence distinguishing it from kb_documents_update reinforces the boundary against the most confusable sibling.

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 concrete prerequisites (document must live in the same tenant; tenant scope needs admin, project/group need editor) and redirects body editing to kb_documents_update. It stops short of naming kb_rules_unset as the inverse operation or stating when not to use this tool, so it is clear context rather than full when/when-not routing.

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