get_document

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

Annotations declare readOnlyHint=true, and description adds behavioral details: include_home_page_content_html fills content_html with raw HTML, and that body is inline prose only. This goes beyond annotations to clarify output limitations and usage context. No contradictions.

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?

Four sentences, front-loaded with purpose, then parameter explanation, then limitation, then warning. Every sentence adds value; no redundancy or filler. Highly 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 the tool has an output schema, return values are handled. Description covers purpose, special parameter behavior, relationship with sibling tools, and a critical usage warning. For a read-only metadata tool, this is complete and actionable.

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 covers all 4 parameters with descriptions (100% coverage). Description adds extra value for include_home_page_content_html: it's the required source for update_document, and warns about blanked body. This enriches understanding beyond 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?

Description clearly states 'Get a document's metadata' and lists fields. It distinguishes from sibling tools by explaining that headings and embedded work items render via read_document, and that include_home_page_content_html is needed for update_document. The verb 'get' and resource 'document' are specific and match the tool name.

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?

Description guides when to use include_home_page_content_html (for round-trip editing) and warns 'Never feed back a blanked (flag=False) body.' It implies that for rendering content, read_document should be used instead. No explicit when-not-to-use, but context is clear.

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