baton_init

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

With no annotations, the description carries the behavioral burden. It states what the tool creates (.baton/ directory) and what it modifies (symlinks CLAUDE.md and AGENTS.md), which is good. However, it does not disclose potential side effects such as overwriting existing files, whether the symlink replaces one side, idempotency, or whether the tool fails if one of the files does not exist.

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 a single, efficiently structured sentence that front-loads the purpose and then lists the concrete actions. Every word earns its place, and it avoids redundancy with the schema.

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 tool with no annotations, no output schema, and an undocumented parameter, the description is incomplete. An agent knows the broad setup intent but not what value to pass for 'project,' whether the tool needs to be run from a particular directory, or what the success/failure behavior looks like. The missing parameter guidance is the most significant gap.

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 schema has one parameter ('project') with zero description coverage, and the tool description never mentions 'project,' its format, default behavior, or how it affects the setup. Since schema coverage is 0%, the description had a full responsibility to explain this parameter and completely failed to do so.

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 names a specific verb ('Set up'), a specific resource ('Baton for a project'), and the concrete actions ('create .baton/' and 'bridge CLAUDE.md <-> AGENTS.md (symlink)'). This clearly distinguishes it from sibling tools like baton_status, baton_pass, or baton_history, which are clearly operational rather than initialization actions.

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 implies when to use this tool: when setting up Baton for a new project, and it explains the intended outcome. It does not explicitly name alternatives or exclusions, but the init/operation distinction among siblings is strong enough that an agent can infer the correct context.

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