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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description goes far beyond them, disclosing side effects (mention.created events emitted to referenced principals), taint propagation from derived_from and content_origin, the 409 contention response with Retry-After, human-lock rejection, token-scope restrictions, and the compact default response. These are exactly the mutation behaviors an agent needs to predict consequences, and none are duplicated from structured fields.

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 purpose is front-loaded, and the content is dense with no filler, but much of it is written in telegraphic fragments ('a tainted source taints it; content_origin other than internal taints it') that require re-reading. It would read better as structured bullets or short labeled clauses given the amount of distinct behavior packed in.

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?

An output schema exists, so the description need not enumerate return fields, and it still usefully states the compact default versus include_content=true. For a 16-parameter mutation tool this is a substantial disclosure, though the undocumented session_batch_id and return_current_on_conflict leave real gaps for correct invocation.

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 only 6% across 16 parameters, so the description must compensate; it does explain the semantics of mentions, derived_from, content_origin, resolves_recall, doc_type, expected_version, and include_content. However, it says nothing about agent, title, namespace, frontmatter, session_batch_id, or return_current_on_conflict, leaving roughly half the parameters undocumented in both places.

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 gives a specific verb and resource: 'Create or update a shared Markdown document with JSON properties,' which an agent can distinguish from read-only siblings like list_documents or recall_document. It also hints at the boundary with append_entries via the doc_type=log note, but it never explicitly names the sibling to prefer over this one, so differentiation is partial.

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 states the create-vs-update selection rule clearly (expected_version=0 creates, otherwise pass the current version) and tells the agent to fall back to 'patch a section' or wait for Retry-After when contention occurs. It also lists exclusions (human-locked documents reject agent writes, SCOUT tokens limited to allowed namespaces). It lacks explicit guidance on when to use upsert_many or patch_doc_section instead of this tool, so it stops short of full alternative routing.

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