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

Adds substantial behavior beyond the annotations: the 50-file cap with pre-conversion rejection, that source .eml files are left in place, that subfolders are mirrored into output_directory, and that errors carry a file plus a sanitized error_code rather than raw exception text. That is exactly the operational context an agent needs before spending a large batch run.

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?

Front-loads the core action, then constraints, then output contract, then the sibling pointer — each sentence carries distinct information with no filler. Length is proportionate to a 15-parameter batch tool.

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 output schema exists, and the description still usefully summarizes the JSON summary shape, so return values are covered. However, for a tool with 15 options and an enum-based preset system, the complete absence of guidance on how the conversion options interact (preset vs individual strip_* flags) leaves a real gap.

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 0% across 15 parameters, so the description carries the full burden — but it only explains output_directory (required, receives Markdown, mirrors subfolders). The 12 conversion flags and 3 enums (preset, thread_mode, thread_order) are entirely undocumented, so an agent cannot tell what 'clean' vs 'verbose' preset or 'structured' thread_mode does.

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?

Opens with a specific verb and resource: 'Batch convert all .eml files in a directory to Markdown,' which immediately separates it from the single-file convert_eml. It does not explicitly contrast with convert_mbox or convert_eml_to_bundle, so sibling differentiation is only partial.

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?

Gives concrete usage context (recursive .eml discovery, hard cap of 50 files with upfront rejection) and routes the agent to convert_eml for reading back individual converted content. It stops short of stating when-not to use it, e.g. for mbox archives, which is left to inference from sibling names.

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?

Goes well beyond the annotations: it discloses the file-writing side effect of output_path, that attachments are listed but not written, the per-preset stripping behavior, and that individual flags override presets. The described write behavior is consistent with readOnlyHint=false and destructiveHint=false.

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?

Front-loaded with the primary behavior, then organized into short paragraphs and a bulleted preset list that is genuinely useful given the empty schema descriptions. Slightly verbose on the forward-quoting edge case, but nothing extraneous.

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?

Covers the entity, the output shape, the disk side effect, and the preset/flag interaction, and an output schema exists so return-value detail is not owed. The remaining gap is semantics for the unlisted boolean flags in a 14-parameter tool.

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 0%, so the description carries the param burden and it partially does: all four preset values and both thread_mode values are given meaning, and output_path behavior is stated. However, thread_order, no_calendar_summary, embed_inline_images, and several strip_* flags are never characterized, leaving half the surface to title-only inference.

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?

States a specific verb and resource plus the exact output format ('Convert a .eml email file to Markdown with YAML front matter'). It also names the sibling convert_eml_to_bundle and the distinct condition that selects it, so an agent can separate the two without reading schemas.

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 routes attachment-saving use cases to convert_eml_to_bundle and explains the thread_mode and preset choices in operational terms. It does not address when convert_directory or convert_mbox should be preferred over this single-file tool, leaving the batch-vs-single decision implied.

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 declare destructiveHint=false and readOnlyHint=false, and the description usefully adds that the original .eml is copied and left untouched, plus that unsupported modes are rejected rather than silently downgraded. It lists the returned fields, giving concrete expectations. No contradiction with annotations; only missing detail is failure behavior (e.g., existing bundle directory).

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 output artifact is described first, then the source_handling caveat, then the return shape — a sensible front-loaded order. Paragraph breaks are used well. Minor redundancy: the return JSON is listed despite an output schema existing.

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?

An output schema exists, so the return-value recap is not strictly needed, and the description covers artifact creation and the source-preservation contract. But with 15 parameters at 0% schema coverage and no mention of the preset/thread options that materially change output, an agent cannot choose parameters confidently from this definition alone.

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 0% across 15 parameters, and the description documents only source_handling. The four enums (preset, thread_mode, thread_order, source_handling) and the ten boolean knobs (strip_signatures, embed_inline_images, include_all_headers, etc.) are left entirely to name inference, so the description does not compensate for the coverage gap.

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 gives a specific verb and resource — convert a .eml file into a self-contained bundle of markdown plus extracted attachments — and clarifies what the output artifact is. It does not explicitly distinguish itself from sibling convert_eml, so the caller must infer the difference from the 'bundle' vs. single-conversion wording.

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?

It clearly states the MCP-level constraint: source_handling only accepts 'copy' here, and 'move'/'delete' must go through the CLI or Python API. That is a genuine when/when-not statement. It stops short of routing between this tool and convert_eml/convert_directory/convert_mbox, which is the remaining 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?

Adds substantial context beyond annotations: hard 256 MiB and 1000-message caps, the truncated=true signal, the requirement that output_directory be supplied, one .md per message vs bundle directories, a collision-safe report, and the guarantee that the source archive is never modified. It also clarifies negative behavior (no cancellation, caps are not a time limit), which is exactly the kind of trap an agent would otherwise fall into.

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?

Front-loads the core purpose in the first sentence, then groups constraints, output behavior, and return shape into short paragraphs. Dense but every sentence carries information an agent needs; no filler or restatement of the name.

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?

Limits, rejection cases, side effects, and return shape are all covered, and an output schema exists so return values need no further explanation. The gap is the undocumented parameter surface: an agent can call this correctly with defaults, but cannot make informed use of the 14 optional formatting toggles.

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 0% across 16 parameters, so the description carries the full burden, yet it only touches output_directory (already marked required in schema) and bundles=true. Fourteen parameters — preset, dry_run, thread_mode, thread_order, include_raw_html, embed_inline_images, no_calendar_summary, and all the strip_* toggles — get no explanation of what they change or when to set them.

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?

States a specific verb and resource ('Convert one flat .mbox archive ... to Markdown files') with its scope ('one flat', example Gmail Takeout). The distinction from siblings is implicit but strong: convert_directory handles directories, which the description explicitly rejects, and the format (.mbox vs .eml) separates it from convert_eml.

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?

Gives explicit when-not conditions (compressed archives and Apple Mail .mbox directories are rejected) and a named alternative for out-of-scope work ('use the dead-letter CLI for larger archives'). It does not explicitly route between convert_eml/convert_directory, but the input-format constraint makes the choice unambiguous.

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?

Consistent with readOnlyHint=true and openWorldHint=false, and adds value beyond them by stating no permanent files are written and enumerating the return-state vocabulary (normal/degraded/review_recommended) plus conditional keys. Falls short of disclosing limits, cost, or when 'degraded' should trigger a re-run.

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?

Front-loaded with purpose, then usage, then return contract; no filler. The long enumeration of return keys is slightly heavy given an output schema exists, but it is organized and readable.

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?

Return values are well covered even though an output schema exists, and safety context is adequate. However, for a tool with 13 parameters and zero schema descriptions, omitting any parameter guidance leaves a genuine gap an agent would hit when deciding preset/thread/strip behavior.

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?

Thirteen parameters with 0% schema description coverage, and the description explains none of them — preset, thread_mode, thread_order, and the eight strip_*/include_* flags are opaque. The only indirect hint is stripped_images appearing conditionally when images were removed, which barely signals the stripping flags.

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?

States a specific verb and resource ('Inspect email quality and structure') and differentiates from the convert_* siblings by noting it does not write permanent files. A clear read-only inspection tool, though it doesn't name the siblings explicitly.

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?

Gives two concrete situations: assess conversion quality before committing, or troubleshoot problematic .eml files. This implicitly routes agents away from convert_eml when they only want inspection, but no alternative is named outright.

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