Get DOCX styles

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

Annotations already declare readOnlyHint=true. Description adds critical behavioral traits: pagination (offset, limit, has_more), the section field appearing only in the first batch, and the requirement to merge batches client-side. 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?

Two sentences with zero fluff. First sentence states purpose and return fields. Second sentence adds the key behavioral note about section and merge instruction. Front-loaded and 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 no output schema, description fully explains return fields: paragraph_styles, total, offset, limit, has_more. Also covers pagination logic, special behavior of section, and integration with sibling tool write_styles_to_docx. No gaps.

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 baseline is 3. Description adds context beyond schema: explains that offset=0 triggers inclusion of the section field, and that limit controls batch size. This extra behavioral detail compensates for the high coverage.

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?

Clearly states verb-resource pair: 'Read a paginated batch of paragraph style definitions from a .docx file.' Distinct from siblings like get_contents_from_docx and write_styles_to_docx by specifying paragraph styles and the paginated batch behavior.

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?

Provides explicit guidance to merge batches client-side before calling write_styles_to_docx, linking the tool to its sibling in a workflow. Lacks explicit when-not-to-use or alternatives, but the pagination description and sibling context make usage clear.

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