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

With readOnly/idempotent/non-destructive already in annotations, the description adds substantial extra behavior: download-permission and household connected-document requirements, rate limiting, release logging in household access history, role-dependent scope (advisors and scoped specialists vs managed-program roles), and explicit caveats that the returned metadata does not verify source contents, extracted facts, or financial balances.

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 sentence is a good front-load, but the remainder is one long run-on block that interleaves return values, version tokens, permission rules, scoping, and URL construction advice. Most sentences carry real content, but the lack of grouping makes it hard to scan and forces the reader to disentangle purpose from caveats.

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, so the description must explain returns, and it does: id, optional sourceVersion with version token/revision time/extraction-generation marker, X1-authored documentUrl, and summary. It also covers permissions and scope-based visibility. It is close to complete for a four-parameter listing read, with only minor gaps in pagination/inventory shape.

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 the schema already documents all four parameters, establishing a baseline of 3. The description does add context for documentId (an exact own-account lookup may surface a closed sourceVersion) and for what summary holds, but limit/category/clientId get no added semantics beyond the schema.

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 pins a specific verb and resource: 'Canonical MCP read for vault document inventory,' and the text distinguishes itself from mounted siblings get_document_content and get_document_download_url. 'Inventory' communicates a listing read, though the description never plainly says it returns a list of documents, so the purpose is clear but partly inferential.

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 explicit routing: on external professional connectors use get_document_content or get_document_download_url (once per document id, when mounted), otherwise open the document in X1. It also states the access conditions under which this applies. It stops short of contrasting with the many sibling search_* document tools, so the alternative-selection guidance is strong but not exhaustive.

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