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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries the burden — and it delivers richly: canonicality behavior (trust actual_tool_output, don't add a state-recovery call), idempotency guidance (retry key or inspect refreshed state), the evidence-is-not-completion semantic, prerequisites, and an explicit confirmation boundary describing the operation as a reversible save. Nothing contradicts the annotations; 'reversible save' is consistent with destructiveHint=false.

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 long (~200 words) but every sentence earns its place: purpose, sibling routing, role constraints, prerequisites, canonicality, idempotency, and confirmation boundary. It is front-loaded with the core action before moving to constraints. The final confirmation-boundary sentence is a bit of a category dump and could be tightened, which keeps this from a 5.

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 14-parameter tool with nested objects, role-based restrictions, no output schema, and many siblings, the description covers selection, invocation workflow, prerequisites, retry semantics, and output handling. Since no output schema exists, the canonicality statement ('trust the returned actual_tool_output and context_engineering') partially compensates for not describing the return shape, though explicit output structure would make it fully complete.

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 71% and most parameters (filePath, fileHash, factId, covers, workItemId, companyId, itemLimit, professional, _corply_context) already carry solid descriptions in the schema itself. The description adds workflow-level meaning beyond the schema by tying filePath/fileHash to the server-returned values from upload_operating_evidence and linking evidence ids to work-item transitions. It does not enumerate every parameter, but the schema does the heavy lifting, so the baseline 3 applies.

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 opening sentence names a specific verb and resource — 'Record a company-owned evidence artifact' — and adds the secondary behavior of freshly resolving the plan. It explicitly differentiates from upload_operating_evidence and submit_operating_fact_evidence by naming them and explaining when each applies. The phrase 'freshly resolve the plan' is slightly ambiguous (re-resolve vs. update) but the overall purpose is clear and distinct from record_operating_event and record_operating_fact.

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 explicit routing: new files go through upload_operating_evidence first, founder-uploaded documents go through submit_operating_fact_evidence for operator review, and evidence ids attach when transitioning a work item. It also states exclusions ('A guidance link or model assertion is never professional evidence') and role constraints (only operators may directly promote an evidence-confirmed fact, professional determinations require named reviewer credentials). This is exemplary when-to-use guidance with named alternatives.

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