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

Annotations are minimal (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description carries the burden. It adds useful behavioral context: the tool returns a server-computed SHA-256, stores bytes in a canonical private prefix, and is described as a 'reversible save' requiring no additional confirmation. It also gives operational advice to 'trust the returned actual_tool_output and context_engineering instead of adding a state-recovery call.' These details go beyond the annotations and help the agent predict side effects, though generic boilerplate weakens precision.

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 first two sentences are tight and front-loaded with purpose and usage. However, the trailing sections (Prerequisite, Canonicality, Idempotency, Confirmation boundary) contain generic, boilerplate language that is not tool-specific and consumes many words. Phrases like 'plus every prerequisite stated above' and 'this read, reversible save, explicit fact/evidence record, link preparation, plan refresh...' are vague and dilute the clarity. The structure is organized but not maximally efficient.

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 5 parameters and no output schema, the description covers the critical flow: upload exact bytes, receive SHA-256, then feed into record_operating_evidence. It mentions the active-company scope, a large-file alternative, and prerequisites. It does not explain fileName/contentType semantics, error handling, or _corply_context details, but for the intended use case the description is sufficiently complete to allow correct invocation and downstream action.

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 60%, with descriptions only for companyId and dataBase64. The description reinforces dataBase64 semantics ('actual base64 file bytes', 'never invent bytes from a description') and mentions the active-company scope, which clarifies companyId. However, it adds nothing about fileName, contentType, or _corply_context, so the remaining 40% of parameters remain under-documented. The description adds some value but does not fully compensate for the gap.

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 states a specific action ('Store exact caller-supplied evidence bytes'), a specific resource ('the active company's private canonical evidence prefix'), and a concrete outcome ('return the server-computed SHA-256 needed by record_operating_evidence'). It clearly differentiates from sibling tools by naming the dependent tool and the return value, leaving no ambiguity about what this tool does.

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?

Explicit when-to-use guidance is present: 'Use only when the client has supplied the actual base64 file bytes; never invent bytes from a description.' It also identifies an alternative path for large files: 'Browser/desktop clients should use POST /operating/evidence/upload for files larger than the MCP limit.' This gives the agent a clear decision boundary and names a distinct alternative.

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