start_session

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

No annotations are provided, so the description carries full weight. It does an excellent job of disclosing side effects: it states it is 'side-effecting (class B per D99.V)', writes session state, and uses the 'D22 start lock' during execution. It also specifies what resources are affected (checkpoint, git status, lock) and provides a reference to a classification system (D99.V) for risk assessment.

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 concise, three sentences, and front-loads the primary action. It efficiently packs essential details: what it does, what it returns, and what side effects to expect. Every sentence adds value, from the core function to the side-effect warning.

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?

Given the tool's complexity (multiple internal steps: checkpoint, git status, lock) and lack of output schema, the description covers the key aspects. It explains the side effects, returns, and even classifies the side-effect level. It could potentially specify what happens if the lock is already held, but that's a minor omission given the details provided.

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 input schema has one parameter 'task' with only a pattern requiring non-space characters. The description doesn't explicitly define 'task', but it mentions that the session creation is the main action. Since there's only one parameter and it's not described in the schema beyond the pattern, the description could have hinted at what 'task' means. However, given the schema coverage is 0%, the description's silence on 'task' is a minor gap, but the low complexity (1 param) mitigates the impact. The description adds value by explaining the side effects but not the parameter semantics.

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 clearly states the tool's purpose: starting a VibeRevert session. It specifies the concrete actions (create inner checkpoint, capture git status, acquire lock) and the return values (session id, checkpoint id, start timestamp). While the sibling tools are listed, the description itself includes enough specificity to distinguish it from potential siblings like create_checkpoint.

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 implies when to use this tool (start of a session) and notes it acquires a lock, which hints at concurrency management. It doesn't explicitly say when not to use it or name alternative tools, but the context of session initialization and the lock acquisition gives clear usage context. The mention of 'start lock' suggests a prerequisite or constraint.

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