get_body_text

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains how tracked changes are handled (included/excluded), how hyperlinks are treated, how paragraphs are separated, and that footnotes are returned separately. It also specifies the output JSON format. This is comprehensive and leaves little ambiguity about the tool's behavior.

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 five sentences, each adding distinct value: main purpose, accepted view inclusion, hyperlink handling, paragraph formatting, and output structure. It is front-loaded with the core purpose and efficiently covers key details without 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?

Given the tool's simplicity (one optional parameter, clear output format described in the description), the description is complete. It covers all necessary aspects: what the tool returns, how it handles tracked changes and elements, and the output structure. There are no missing details that would prevent 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?

The input schema has one parameter (document_handle) with no description and 0% schema coverage. The description does not add any semantic context about this parameter (e.g., what a document handle is, how to obtain it, or its default behavior). Since the schema coverage is low, the description should compensate, but it fails to do so. The parameter name is self-explanatory, but the description adds no value 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 description clearly states it returns the full accepted-view text of the document, specifying that it includes inserted text, excludes deleted text, includes hyperlink runs, joins paragraphs with newlines, and returns footnotes separately. This distinguishes it from sibling tools like get_footnotes (returns only footnotes) and get_tracked_changes (returns changes themselves). The verb 'Return' and the specific resource 'full accepted-view text' make the purpose unambiguous.

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 implies this tool is used when the clean, accepted text (with tracked changes resolved) is needed, but it does not explicitly state when to use it over alternatives, such as when to prefer get_body_text over get_bookmarked_text or get_footnotes. No exclusion criteria or when-not-to-use guidance is provided.

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