keystone_new_action

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the creation of a markdown file at a path, but it does not mention side effects such as whether existing files are overwritten, how the `force` flag affects behavior, or any prerequisites/permissions. This is a significant gap for a scaffolding tool that mutates the filesystem.

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 front-loaded with the concrete action and path in the first sentence, then adds concise conceptual context with examples and sibling distinctions. No sentences are wasted.

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 is simple (2 params, no nested objects) and an output schema exists, so return values don't need explanation. But the description omits the meaning/effect of `force` and any overwrite behavior, leaving an agent to guess. It adequately explains purpose and relation to playbooks/skills, but not enough for full autonomous 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?

The `name` parameter is indirectly explained by the `<name>.md` placeholder in the path. However, the `force` parameter is not described at all, and schema coverage is 0%, so the description must compensate but fails to do so for half the parameters.

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 specific verb ('Scaffold') and resource ('new action markdown') plus the exact destination path (.keystone/harness/actions/<name>.md). It also distinguishes actions from playbooks and skills, though it does not contrast with every sibling new_* tool.

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?

It provides clear usage context by defining actions as 'short, focused operations' and explicitly contrasts them with playbooks (orchestration) and skills (procedural how-to via skill://). This gives the agent enough to choose between this tool and the most closely related siblings.

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