validate_document

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

With no annotations, the description carries the full burden and does substantial work: it discloses the server-side persistence side effect, that v1–43 documents are auto-migrated, that local-path image srcs are read and embedded, and that an existing documentId is preserved. It also specifies the error payload shape (page, node, extra/missing key, suggested documentVersion). Remaining gaps are auth/permission requirements, size limits, and what happens to an existing document's prior contents on re-validation.

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 core purpose, side effect and error format are front-loaded in the first sentence, which is good. But the second half is a dense inline mini-spec that partially duplicates the dingcard://schema/freeform resource the description itself tells the agent to read, making it longer than necessary.

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?

There is no output schema and no annotations, so the description must explain returns and behavior — and it does: documentId/version on success, structured error reasons on failure, plus migration and image-embedding side effects. For a 4-parameter, zero-required tool it is close to complete; only permission and overwrite semantics are missing.

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 100%, so baseline would be 3, but the description adds real meaning for the primary `document` parameter: the v44 shape (documentVersion, slides, node type enumeration, common required keys, exact key matching, global id uniqueness) and a pointer to the authoritative schema resource. It does not add anything for documentPath or includeDocument beyond what 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 states a specific verb and resource: validate a freeform-canvas v44 document, and adds the key distinguishing behavior that a valid document is persisted server-side and a documentId returned. It is easy to distinguish from read-oriented siblings like get_document or inspect_document, though it never contrasts itself with the similarly-named check_document sibling, which an agent could easily confuse it with.

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?

It gives concrete workflow guidance: read the schema resource or get_guide("document-model") before writing, and if unsure, submit a rough draft for validation and iterate on the returned errors. That is a clear 'when to use' with an implied call pattern. It stops short of naming alternatives (check_document vs inspect_document vs this tool) or stating when validation is unnecessary.

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