Iteration Layer

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds useful context: supported formats (extensive list), email attachment extraction, and max file size (50 MB). 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?

Description is well-structured, front-loaded with core purpose, then usage guidance, then format list. No redundant sentences; efficient at ~120 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?

With no output schema, description explains return values. Lists many formats and mentions email attachment extraction. Lacks details on failure handling or image resolution limits, but overall sufficient for a tool with nested parameter and no output schema.

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 simple guidance on file object requirements but does not add significant meaning beyond the detailed 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 'Convert a document or image to clean markdown' and specifies the return format (name, mime_type, markdown, description). It distinguishes from sibling tool extract_document by noting the difference in output type.

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?

Explicitly advises when to use ('need full document content in markdown for summarization, search, or agent context') and when not to ('use extract_document instead when you need typed structured fields').

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by detailing output format (extracted values with confidence scores and source citations), supported file types, max file size, and email attachment extraction. It does not contradict annotations and provides useful context beyond structured fields.

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 yet comprehensive, front-loading the purpose and key parameters. It is structured logically: purpose, parameter explanation, usage guidance, supported formats, and constraints. Every sentence adds value with no redundancy.

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 complexity (nested parameters, many field types), the description adequately covers core aspects: what it does, how to use it, when to use alternatives, supported formats, output characteristics, and constraints (max file size). It lacks detailed error handling or performance notes, but the annotations cover safety, so completeness is strong.

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 description coverage is 100%, so baseline is 3. The description adds value by summarizing the schema's purpose, mentioning typed fields, and giving a practical example (arrays for invoice line items). This aids the agent in understanding parameter usage beyond schema definitions.

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 the tool extracts structured data from documents using AI. It specifies the verb (extract), resource (documents), and output type (structured data). It distinguishes from sibling tools by referencing convert_document_to_markdown for full text extraction, ensuring the agent knows when to choose this tool.

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 explicitly advises using this tool for typed structured data and recommends convert_document_to_markdown when full document text is needed. It could be improved by providing more when-not-to-use guidance for other siblings, but the existing alternative is clear and actionable.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the tool is clearly non-destructive and safe. The description adds context about fetch_options (locale, user agent, auth, headers, timeout, JavaScript rendering) which are behavioral details beyond annotations, but it does not contradict 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 four sentences long, front-loaded with the primary purpose. It is reasonably concise, though the third sentence could be integrated more efficiently. No wasted words, but the repetition of schema details could be trimmed.

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 lacks information about the tool's output or return format (no output schema exists). While the schema parameter defines the extraction schema, the agent is left to infer the response structure. An explicit mention of what the tool returns would improve completeness. No mention of error scenarios or rate limits, but annotations cover safety and idempotency.

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 description coverage is 100%, so the baseline is 3. The description restates that the 'file' parameter must be a URL with 'type', 'url', and optional 'fetch_options', which adds marginal value by reinforcing the schema but does not introduce new semantic information beyond what the schema's descriptions already provide.

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 the tool's action (extract structured data) and resource (public website URL). It distinguishes from generic file extraction by explicitly mentioning 'website-specific fetching' and contrasting with 'wrapping a URL inside the generic files array', which helps differentiate it from sibling tools like extract_document.

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 provides explicit guidance on when to use this tool ('when you want website-specific fetching instead of wrapping a URL inside the generic files array'). However, it does not explicitly name the alternative tool or provide conditions for when NOT to use it, which is a minor gap.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, providing a solid safety profile. The description adds useful behavioral context beyond annotations, such as the return of a binary document buffer with correct MIME type, default fonts (PlusJakartaSans for body, Outfit for headings), and default page settings (A4, 72pt margins). However, it does not elaborate on side effects or permissions, but these are covered by 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 long but appropriately so given the complexity of the tool. It front-loads the core purpose and format options, then lists content blocks, defaults, and ends with usage guidance and sibling tool references. Every sentence adds value, though the description could be slightly more concise without losing clarity.

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 complexity (two parameters with deeply nested objects), the description covers the essential aspects: supported formats, document structure, content block types, default styles, custom fonts, headers/footers, and return type. There is no output schema, but the description states it returns a binary document buffer with correct MIME type. This is a well-rounded overview that enables an AI to use the tool effectively.

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 description coverage is 100%, so baseline is 3. The description adds value by summarizing the document parameter's structure ('metadata, page settings, styles, and content blocks'), listing supported content blocks, and mentioning optionality of styles and page settings with sensible defaults applied. This goes beyond what the schema descriptions individually provide.

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 generates PDF, DOCX, PPTX, or EPUB documents from a structured document definition. It specifies the verb 'Generate' and the resource 'documents', lists supported formats, and explicitly distinguishes itself from sibling tools like generate_sheet and generate_image by stating when to use each.

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 provides explicit guidance on when to use this tool ('Use this for PDFs, DOCX, PPTX, or EPUB generated from structured content') and explicitly names alternatives ('Use generate_sheet for tabular spreadsheet output and generate_image for layered image output'). This clearly differentiates usage from related tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, indicating a safe operation. The description adds value by detailing compositing behavior (z-order, per-layer transformations) and font/font customization, which goes beyond the 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 a single, well-structured paragraph that front-loads the core purpose. Every sentence adds essential information without redundancy or fluff.

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 thoroughly explains input structure and layer types, but fails to describe the output format or return value (e.g., how the generated image is returned). Since there is no output schema, the description should cover this.

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%, but the description adds meaning by explaining the overall compositing process, mentioning built-in fonts, and listing barcode formats and output options. This context helps an agent understand parameter interactions 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 that the tool generates images from layer compositions, specifying a concrete action and resource. It lists layer types and output formats, but does not explicitly distinguish from sibling tools like transform_image, missing some differentiation.

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 provides no guidance on when to use this tool versus alternatives. It does not mention use cases, prerequisites, or when to avoid using it.

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

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

Annotations already indicate read-only and non-destructive behavior. The description adds that it 'Returns a binary spreadsheet buffer with the correct MIME type,' confirming no side effects. It also discloses support for rich styling, merged cells, formulas, and custom fonts, which are beyond annotation scope.

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 front-loaded with the core purpose in the first sentence and then logically expands into details about formatting, styles, and special features. It is fairly concise given the complexity, though a few sentences could be slightly trimmed without losing meaning.

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 complexity (4 parameters with nested objects, no output schema), the description adequately covers return type (binary buffer), MIME type, and key capabilities. It omits error handling and size limits, but for a generation tool, this is sufficient for effective use.

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 description coverage is 100%, so baseline is 3. The description adds value by explaining that XLSX supports rich styling, merged cells via spans, Excel formulas, 162 currency codes, and configurable number styles—enriching understanding beyond the schema's structural definitions.

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 generates XLSX, CSV, or Markdown spreadsheets from tabular data, explicitly distinguishing from narrative documents via sibling tool 'generate_document'. The verb 'generate' with specific formats and 'tabular data' is precise and 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?

Explicitly states 'Use this for tabular exports rather than narrative documents,' providing a clear alternative. It also hints at format selection (XLSX vs CSV vs Markdown) but does not detail when to choose each, leaving some ambiguity.

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

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

Annotations indicate readOnlyHint and idempotentHint, implying no mutation. The description adds behavioral details such as max file size, supported output formats, and the nature of operations (sequential pipeline, AI capabilities). No contradiction with annotations; readOnlyHint aligns with the concept of creating a new transformed image.

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 no redundant sentences. It front-loads the purpose and key constraint (up to 30 operations), and the list of operations is efficiently given as a comma-separated list.

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 complexity (many operations, nested objects), the description and schema together are comprehensive. The description mentions output formats and max file size, compensating for the lack of an output schema. It could include more on auth or rate limits, but overall it is complete.

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 description coverage is 100%, so baseline is 3. The description adds value by explaining the operations parameter as an ordered pipeline applied from first to last step, and listing all operations, which provides context beyond schema details.

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 the tool transforms and manipulates images with a pipeline of operations. It distinguishes itself from the sibling tool generate_image by specifying it edits existing images rather than generates new ones from scratch.

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 explicitly states when to use this tool (edit existing images) and implicitly differentiates from image generation. It does not mention when not to use or provide explicit alternatives, but the context is clear enough for an agent.

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