extract_structure

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

Leverages annotations (readOnlyHint, destructiveHint, idempotentHint) effectively while adding valuable output contract details. Describes exactly what the JSON contains (statistics, heading outline, code block summary with language/line counts, link summary), clarifying what 'structure' means operationally. No contradictions 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?

Three well-constructed sentences: purpose declaration, detailed output specification, and conceptual summary. Zero redundancy—every sentence advances understanding of tool capabilities. Front-loaded with the core action.

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?

Despite no output schema, description comprehensively details return value structure (JSON components: statistics, headings, code blocks with metadata, links with counts). Combined with rich annotations covering behavioral traits, provides complete contractual information needed for agent 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?

Schema coverage is 100% with clear parameter description ('The Markdown text to extract structure from'). Description references 'Markdown document' but adds no additional semantic constraints (size limits, encoding requirements, valid markdown prerequisites) beyond what the schema already provides. Baseline 3 appropriate given complete schema 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?

Excellent specificity: 'Extract' (verb) + 'full structure of a Markdown document' (resource+scope). Distinguishes clearly from siblings like extract_code_blocks and extract_links by emphasizing 'full structure' versus specific elements, and from convert_to_* tools by focusing on structural analysis rather than format transformation.

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 implied usage through output description ('bird's-eye view of document architecture'), indicating this is for structural overview. However, lacks explicit when/when-not guidance or comparisons to siblings like analyze_document or the more specific extraction tools.

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