Start a claim audit

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

Annotations declare readOnlyHint=false and openWorldHint=false, and the description corroborates the mutating nature by disclosing that it 'pins the commit' and returns a protocol to follow. It does not say whether the pinned state is persistent, whether concurrent audits conflict, or what cleanup is required against elliot_audit_finish. Still, the key side effect is surfaced, which is real value beyond the annotations.

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?

A single dense sentence whose first clause states the core purpose and whose remaining clauses front-load the concrete outputs. No filler, no repetition of the title, nothing that could be cut without losing information.

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 no-required-param session-start tool with full schema coverage, no output schema and meaningful annotations, the description covers purpose, side effects, and the returned artifact ('the protocol to follow'). What is missing is lifecycle context: how long an audit stays open and its relationship to elliot_audit_finish. That is a modest gap, not a blocking one.

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% and both parameters are richly documented in the schema, including the default working directory and the fact that 'sources' disables the repo-wide risk sweep. The description adds nothing about either parameter, so it sits at the baseline. The phrase 'lists the files that make claims' loosely gestures at the sources scoping but no more than the schema already says.

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 gives a specific verb and resource (audit whether the repo matches its README/docs/security/pricing claims) and enumerates the concrete effects: pinning the commit, listing claim-bearing files, returning a protocol. That is far more than a restatement of the name. It does not name elliot_audit_finish as the counterpart, so sibling differentiation is only implied by the word 'Start'.

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 verb 'Start' plus 'returns the protocol to follow' implies this is the entry point of a multi-step audit before elliot_record_claim / elliot_audit_finish, but that sequencing is never stated. There are no explicit when-not conditions or named alternatives. The agent must infer the workflow position rather than being told it.

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