knowl_drift

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

Annotations are minimal (title and openWorldHint only), so the description carries the full behavioral burden, and it delivers: the intentional edited-file exclusion with the signal-to-noise rationale, empty-result semantics, preview-by-default vs. apply-flagging behavior that persists to the next session, and the git repository/base-ref prerequisite. No contradiction with annotations.

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 sentences, each earning its place: what it reports, when to use it, the deliberate exclusion with rationale, apply behavior, and the repository prerequisite. The core purpose is front-loaded before caveats, with no 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?

For a 2-parameter tool with no output schema, the description covers detection scope, negative-result semantics, default vs. mutating behavior, and environmental prerequisites. An agent has everything needed to select and invoke the tool correctly without relying on the schema.

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 100%, so the baseline is 3. The description adds value beyond the schema by clarifying that preview is the default path and that `apply` marks matches so the next session sees them flagged rather than trusting them — persistence semantics the schema does not state.

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?

The description opens with a precise statement of what the tool reports — atoms whose cited files the diff deleted or moved, plus symbol evidence that no longer resolves — giving a specific verb, resource, and detection mechanism. It differentiates from siblings like knowl_query or knowl_evidence_list by naming the exact invalidation signal it detects and what it deliberately excludes.

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?

Explicit usage contexts are given: before opening a pull request, before knowl_task_finish on code-touching work, and when asked what a change breaks. It also provides a when-not-to-use signal by stating that edited files are deliberately not reported, and clarifies the empty-result meaning to prevent misreading.

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