ewp_check_record

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

Since annotations are absent, the description carries the burden of behavioral disclosure. It covers the side effect (appends a snapshot), the precondition (ingest role), and the conditional requirement for trusted origin (ingest_attestation). It does not mention whether the operation is destructive, reversible, or how failures are handled. For a mutating append operation, this is a moderate disclosure, but it omits details like whether the original snapshot is preserved.

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 short and front-loads the primary action. It packs essential information (returns new view_id, role requirement, trusted origin detail) into two sentences. It is efficient but slightly dense; it could be a bit more structured with bullet points, but overall every sentence earns its place.

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 (4 params, nested object, no output schema), the description covers core elements but leaves gaps: no explanation of what a VerificationCheck is, what the 'check' object should contain, or what the return format looks like beyond the new_view_id. The description explains some parameter semantics but not enough to fully use the tool without schema. The presence of sibling tools suggests the description could be more complete for an agent to select and invoke correctly.

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 coverage is only 25%, so the description must compensate, and it does: it explains that 'new_view_id' is optional and content-derived when omitted (adding meaning beyond the schema's simple 'optional' description), and it clarifies the role of 'ingest_attestation' as a requirement for trusted origin. It does not detail the structure of 'check', but the schema already uses a generic 'object' type, so the description could add value by specifying expected fields, but it doesn't.

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 action ('Append a VerificationCheck') and the resource (a snapshot), and adds the key behavior of creating a new snapshot from the latest one. It mentions the return value (new view_id), which helps distinguish it from sibling tools like ewp_evidence_view_get. However, it does not explicitly contrast with siblings such as ewp_evidence_record, so it is clear but not fully differentiated.

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 some usage context: it mentions the ingest role requirement and trusted origin requiring ingest_attestation, which hints at when this tool is appropriate (when caller has ingest role). It does not explicitly state when not to use it or point to alternatives, but the role requirement is a clear gate. Given the sibling set includes similar tools, more explicit when-to-use guidance would be helpful.

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