OKF: Convert Wikilinks

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

The description adds substantial behavioral detail beyond the annotations: writes go through the normal write path, git commit occurs if configured, re-running is safe, resolvability determines conversion, and the link graph is preserved exactly. This gives an agent a clear model of side effects and safety considerations, complementing the destructiveHint and idempotentHint 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?

The description is compact, front-loaded with the primary action, and every subsequent sentence adds meaningful information about behavior, edge cases, or safety. There is no filler or repetition that detracts from its usefulness.

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 has a rich description, an output schema, and annotations covering mutability and idempotency. The description covers the main action, scope, exceptions, side effects, re-run behavior, and link-graph preservation, leaving no material gap for an agent to select and invoke the tool correctly.

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?

The single parameter 'folder' is fully described in the schema with default and behavior (restrict to folder subtree, omit for whole vault). The description reiterates the 'vault or folder' scope but does not add new parameter-level semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.

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 states a specific action ('Rewrite wikilinks as OKF bundle-root-absolute markdown links') and identifies the exact resource (resolvable wikilinks in the vault or a folder). It clearly differentiates this migration tool from siblings like okf_validate and okf_generate_index by describing its unique transformation purpose.

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?

The description clearly establishes when to use the tool: during an OKF migration to convert wikilinks to markdown links. It also specifies constraints on usage, such as only converting indexed targets and leaving unresolvable links untouched. It does not explicitly name alternative tools, but the context is strong enough to make the intended use clear.

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