codebase_watch

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

With no annotations, the description must disclose behavior. It mentions that starting 'first runs an incremental update to catch up, then watches for changes' and covers environment variable effects. However, it says nothing about the behavior of 'stop' or 'status' actions, nor about side effects like index modification. This partial disclosure is useful but incomplete for a tool with three actions.

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 two sentences, front-loading the core purpose and then adding a behavioral detail. It is efficient with no wasted words, earning a high score for conciseness.

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 an enum action and a projectPath, and no output schema. The description explains the start behavior but omits details for stop and status, and does not clarify whether projectPath is needed for all actions (schema lists it as optional). An agent would need to infer behavior for the other actions from the schema's enum, which is insufficient. Completeness is adequate but has gaps.

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 100% for both parameters (action and projectPath), so the schema already documents them. The description adds no additional parameter details, so it relies on the schema. Baseline 3 is appropriate given the high schema coverage.

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: 'Start/stop watching a project directory for file changes and automatically update the index.' It identifies the action (start/stop) and the resource (project directory), which is specific. However, it does not explicitly distinguish itself from sibling tools like codebase_stop or codebase_status, so it lacks explicit differentiation.

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 provides context about the SOCRATICODE_WATCHER environment variable ('manual allows explicit starts only; off rejects starts'), but it does not give guidance on when to use this tool versus alternatives like codebase_stop or codebase_status. There is no mention of alternatives or exclusions, so the agent must infer usage from the action enum.

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