taskguard_add_evidence

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

With no annotations provided, the description carries the full burden. It mentions the types of evidence and linking to done criteria, but it does not disclose side effects (e.g., whether it appends or replaces), error handling, or return values. For a simple add operation, some transparency is present, but more detail would be beneficial.

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: two sentences front-loaded with the core usage instruction. Every sentence adds value, and there is no fluff. It is appropriately sized for the tool's simplicity.

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 no output schema, no annotations, and 8 parameters with 0% schema description, the description is minimal. It lacks details on how evidence integrates with the session, the effect on checkpointIds and doneCriterionIds, and the overall behavior. For a tool in a task management suite, more context is needed for correct 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?

Schema description coverage is 0%, so the description must compensate. It adds meaning by listing evidence kinds (tests, typecheck, etc.) and mentioning 'paths, or URLs', which correspond to parameters. However, it does not explain many parameters like sessionId, checkpointIds, doneCriterionIds, or command, leaving gaps in 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 purpose: 'Call this whenever you have proof of progress' and lists specific evidence types (tests, typecheck, lint, etc.). It effectively distinguishes from sibling tools like taskguard_add_checkpoint or taskguard_update_criterion, which deal with different concepts.

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 gives clear guidance on when to use it ('whenever you have proof of progress') and instructs to link evidence to done criteria. However, it does not explicitly state when not to use it or directly contrast with alternatives among siblings, though the context implies its specific role.

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