get_document

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

Beyond the readOnlyHint annotation, the description details that author/last_updated_by are display names, and that content_html only contains inline prose (headings/work items are elsewhere). It also explains the autoSuspect behavior for round-trip editing. No contradiction with annotations.

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 concise, with each sentence adding value. It front-loads the main purpose, then lists additional returns, and finally explains the optional parameter with necessary caveats. No redundancy or unnecessary words.

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?

The description is comprehensive: it covers what is returned (metadata, outline numbering, autoSuspect), the optional behavior of content_html, limitations (inline prose only), and relationships to sibling tools (read_document, update_document). Given that an output schema exists, the description does not need to detail return values. It addresses potential pitfalls (blanked body) and clarifies name fields.

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?

The input schema already describes parameters, but the description adds crucial context: the include_homepage_content_html flag is the required source for update_document, and the content_html it fills is only inline prose. It also warns against feeding back a blanked body, which is not in the schema. This adds significant value beyond the schema descriptions.

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 clearly states that the tool retrieves a document's metadata including title, type, status, editors, and custom fields. It also mentions returning outline numbering and autoSuspect, and distinguishes from siblings by noting that read_document renders all content while get_document with the flag provides raw HTML for editing, and update_document is used for round-trip.

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 implicitly guides when to use get_document: for metadata and round-trip editing via the flag. It contrasts with read_document (full rendering) and update_document (requires the content from get_document). It also warns about not feeding back a blanked body, providing actionable guidance. However, it does not explicitly list all alternatives or when not to use.

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