evidence

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

The description presents a 'merge' operation against a *persistent* evidence index, which is a state-mutating write, while the annotations declare readOnlyHint=true. That is a direct conflict an agent could act on incorrectly. The only genuine behavioral disclosure beyond the annotations is the association rule (no time/path/PID linkage), which is valuable but is overridden by the read-only contradiction.

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?

Two tight clauses, with the core operation front-loaded and the negative association rule appended as a caveat. There is no filler and no restatement of the title. It is dense but every clause carries signal.

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 seven-parameter tool with zero schema description coverage and no output schema, the definition should explain the two actions, the job-scoping parameters, and pagination behavior. It covers only the query-key concept and one correctness rule, leaving mutation semantics and the majority of inputs unexplained.

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% across seven parameters, so the description carries the full burden and largely fails it. It gestures at query keys ('content hash / signature / same-script invocation ID') but never maps them onto actual parameter names such as 'query' or 'kind'. The jobIds, graphJobId, limit, and offset parameters are not addressed at all, leaving pagination and job scoping undocumented.

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 concrete resource and two operations: merging a persistent evidence index of completed tasks, and querying it by content hash, signature, or same-script invocation ID. That is far more specific than the bare name 'evidence' and an agent can tell what data domain it covers. It does not differentiate itself from any sibling tool, so it stops short of a 5.

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 phrase '已完成任务' (completed tasks) implies a precondition, and the negative rule about not inferring cross-task linkage from time proximity, identical paths, or PIDs is genuinely useful guidance on correct use. However, nothing states when to choose the 'merge' action versus 'query', and no alternative tool is offered for any scenario. Usage is implied rather than stated.

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