Rename feature id

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

With no annotations, the description carries the full burden and does so thoroughly: validation of the feat-NNN-slug shape, refusal on existing folder collision, the exact filesystem mutation, the updated timestamp bump, and the guarantee that the body stays byte-identical. It also discloses the truncated return (frontmatter only), which is precisely the kind of side-effect detail an agent needs before invoking.

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?

Two sentences, front-loaded with the operation, then the validation/refusal/mutation sequence, then the scope limit and return contract. The long first sentence is dense but every clause conveys distinct behavioral information 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?

Covers preconditions (shape validation, existence check), side effects, explicit non-effects (no reference rewrites), and the return shape, and even points to get_feat for the follow-up fetch. Despite an output schema existing, the note about frontmatter-only return is a useful complement rather than a repetition.

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%, so the description must compensate. It defines new_id's required format ('feat-NNN-slug shape') and the collision constraint, plus implies id refers to the existing feature identifier. The 'id' parameter's own format is left implicit, keeping it short of a 5.

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+resource ('Rename an existing feature's id') and enumerates the exact effects: folder rename, frontmatter id rewrite, updated bump. This clearly distinguishes it from generic siblings like edit, update_frontmatter, or update, which do not perform id/folder migration.

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?

Explicitly scopes what the tool does NOT do ('Does not update or search for references to the old id in any other document') and directs the agent to get_feat afterward for the full document. It does not name which sibling to use instead for reference updating (e.g., list_references or edit), so the alternative routing is only partially closed.

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