WordCraft MCP Server

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

Annotations declare non-read-only, non-destructive, non-idempotent, and the description usefully explains why: it writes new outputs beside the input and replaces nothing unless overwrite is true, which materially clarifies the safety profile. It also discloses that multiple inputs are supported and that markup mode changes output content. It stops short of stating permissions or failure 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?

Three tight clauses, front-loaded with the conversion scope, and every sentence carries information about formats or output placement. The 'doc (read)' and 'png (first page)' parentheticals introduce minor ambiguity rather than 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?

There is no output schema, so the description must fully specify behavior; it covers output location and overwrite but omits how the several optional input parameters interact and what the tool returns per file. Adequate for a conversion tool with no required parameters, but not 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?

With 63% schema coverage, the description adds real value for markup, overwrite, and output placement. However, the mutual exclusivity/priority among input_path, input_paths, and input_dir is never explained — a significant gap for an agent choosing among them — and 'png (first page)' conflicts subtly with the schema's 'one image per page' wording.

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 (convert) and resource (documents), and enumerates the supported target formats, so the core operation is unambiguous. It does not differentiate from siblings that overlap in output (render_pages for png, extract_text for txt, create_document for docx), leaving the agent to infer boundaries.

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?

Usage is implied by the format list and by 'Outputs go next to each input or into output_dir', but there is no explicit when-to-use/when-not statement and no sibling alternative is named despite clear overlap with render_pages and extract_text.

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 non-read-only, non-destructive, non-idempotent, closed-world; the description adds useful behavior beyond that — multiple files written per call, a page-1 preview returned, optional docx encryption, and template text prepended to supplied blocks. It does not disclose the re-run/overwrite consequences of the non-idempotent write, which is the remaining gap.

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, front-loaded with the core verb and the capability set, then output formats and return value. The long enumerations are dense but each element maps to real schema surface, so little is wasted — though it reads as a feature list rather than a task-oriented summary.

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?

For a 22-parameter creation tool with no output schema, the description covers the authoring model, output formats and the preview return value, which is the right altitude. It omits nothing dangerous, though it could have flagged that output_dir/output_path are effectively required and how blocks ordering interacts with templates.

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 82%, so the schema already documents nearly every parameter; the description mainly re-lists content block types and formats that the schema's oneOf branches and enum already convey. The template example list ('letter, resume, report') even omits 'sample' that the schema includes, adding no new semantics.

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 ('Write a new document with WordCraft'), then enumerates exactly what can be authored (headings, lists, tables, images, TOC, footnotes) and which formats it saves. However it never names a sibling to distinguish itself from edit_document or convert_document, so the reader must infer 'create vs modify' from the verb alone.

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?

'Starts blank or from a built-in template' implies the fresh-document case, but there is no explicit 'use this instead of edit_document when the document does not exist yet' and no stated prerequisites (e.g. output_dir required for new documents, which only appears in the schema). Usage is inferable, not guided.

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 real behavior beyond annotations: source files are not modified, output naming convention and location (next to input or output_dir), tracked changes make edits reviewable in Word, existing revisions can be accepted/rejected, and personal-info removal is available. Annotations cover safety (non-readonly, non-destructive, non-idempotent), so the description's contribution is the output-side effect, which it delivers.

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?

One dense but well-ordered paragraph that front-loads the core guarantee ('without touching the originals') before enumerating capabilities, ending with the output-location rule. It is long but nearly every clause names a distinct capability; a bulleted structure would improve scanability.

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?

For a 29-parameter, no-required-param mutation tool with no output schema, the description covers the main editing surfaces and the output file convention, but says nothing about return value, preview behavior, or how multiple input_paths/input_dir interact with output naming — gaps the schema alone doesn't close.

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?

With 29 params and only 66% schema coverage, the description usefully maps the conceptual operations to parameter groups: find/replace with match case, whole word, wildcards; comments on found text; tracked changes; accept/reject revisions; append blocks; properties; page setup; headers/footers; remove personal info. It leaves several params (preview, password, export_pages, scale, suffix, formats defaults) undocumented, so not a full 5.

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 (edit existing documents across a listed set of formats) and enumerates the operations it performs, so the agent can tell it apart from create_document (which it references) and convert_document. It stops short of naming the other siblings (get_document_info, extract_text, render_pages) as non-overlapping.

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?

Implicit usage is clear: existing documents only, originals untouched, output written as <name>_edited.<ext>. The mention of 'same blocks as create_document' is a cross-reference rather than routing guidance, and there is no explicit 'use X instead when...' statement.

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?

The description usefully explains why readOnlyHint=false despite an extraction operation: with save_txt it writes <name>.txt files. It also discloses the max_chars truncation behavior per document. It stops short of covering overwrite behavior or what happens when output files already exist, which is the remaining risky surface.

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 compact sentences with no filler, and the core resource statement is front-loaded. The parenthetical format list is slightly noisy but earns its place by defining scope.

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?

For an 8-parameter batch tool with no output schema and three mutually exclusive-looking input selectors, the description leaves too much unresolved. It never explains how input_dir, input_path, and input_paths relate, nor where output lands by default, which is the main ambiguity for 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?

Schema coverage is only 38% across 8 parameters. The description adds real meaning for max_chars (per-document cap) and save_txt (writes files), but says nothing about the input_path vs input_dir vs input_paths modes, output_path/output_dir, or overwrite — exactly the parameters an agent is most likely to misuse.

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 the resource (plain text of documents) and enumerates supported formats, plus what is returned and the optional file-writing side effect. It is clear what the tool produces, but it never distinguishes itself from siblings such as convert_document, which an agent could reasonably pick for the same job.

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?

Usage is only implied: the format list suggests 'use this when you need raw text rather than a converted document', but there is no explicit when-to-use statement, no exclusions, and no mention of convert_document or the other extraction-adjacent siblings.

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=false, so the safety profile is covered. The description adds that the tool surfaces comments, tracked changes and optionally structure, which is useful beyond the annotations, but it says nothing about cost, size of output, or behavior when multiple input paths are supplied.

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?

A single sentence that front-loads the returned data and appends the optional structure mode; every clause names concrete artifacts. It is dense but avoids redundancy, though the noun-list opening delays the reader from knowing what action is performed.

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 and 25% parameter coverage, the description should explain the input_dir/input_path/input_paths distinction and the fact that up to 200 paths can be batched, but it does not. An agent still cannot tell whether this handles one document or many, or what the path parameters mean.

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 only 25%: input_dir, input_path and input_paths are undocumented in both schema and description. The description does clarify what 'structure' means (headings, paragraph styles, lists, tables with cell texts), which usefully expands on the schema's terse 'blocks (style, text, tables)' for include_structure, but three of four parameters remain opaque.

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 enumerates exactly what the tool returns (pages, words, paragraphs, sections, comments, tracked changes, properties) and offers an optional structure mode, so the resource and output scope are unambiguous. It never states a verb and does not distinguish itself from siblings like extract_text or render_pages, which also read document content.

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 phrase 'to understand a document before editing it' implies the correct usage context (pre-edit inspection) and implicitly pairs it with edit_document. However, no alternatives are named and no conditions are given for choosing this over extract_text or render_pages, leaving routing to inference.

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, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds real value beyond that by disclosing the content of the probe, including the live state check ('whether the app is running / listening for control'), which tells the agent this inspects runtime state, not just static config.

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?

A single front-loaded sentence with no filler; the colon-delimited facet list is dense but each item is informative. It is slightly list-like rather than prose, but nothing is wasted.

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 zero parameters, no output schema and full annotation coverage, the description carries the burden of explaining what comes back, and it does so thoroughly. Only minor gaps remain, such as whether it fails or reports an error when WordCraft is not installed.

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 tool takes zero parameters, so the baseline is 4. The description correctly implies no input is needed and spends its words on what is returned instead.

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 ('Check') and a specific resource ('the WordCraft installation') and then enumerates the facets inspected (platform, executables, version, engine commands, feature coverage, save formats, running/listening state). That enumeration makes it clearly distinct from get_document_info and list_wordcraft_catalog, though no sibling is named 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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternative is named. The intent (a preflight/diagnostic check before running commands or opening documents) is only implied by the enumerated facets.

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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds substantive behavioral context: commands include parameters and ribbon location, styles depend on a new document or input_path, and formats cover open/save. It does not describe output format or pagination, but it 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 definition is a single dense sentence organized by catalog kind with useful parentheticals and no filler beyond the opening phrase. It is appropriately sized, though it could front-load the listing action more directly instead of starting with 'What WordCraft can do'.

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, the description must carry return-value context; it names the contents of each catalog kind but does not explain output format, size or pagination for 615 commands, or how filter applies across kinds. It remains adequate for a read-only discovery tool because the schema covers the parameters, but clear gaps remain.

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 description explains the meaning of every kind enum value, including the distinction between styles of a new document and styles of input_path. It omits the filter parameter, but the schema documents that at 67% coverage, so the description still adds strong semantic value.

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 enumerates the four catalog types and ties commands to run_wordcraft_commands, making the resource scope clear. It does not use an explicit 'list' verb in prose, but an agent can still identify this as the catalog-discovery tool and distinguish one key sibling relationship.

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 only explicit routing is that commands are 'for run_wordcraft_commands'; there is no direct guidance on when to use this tool instead of get_document_info, open_in_wordcraft, or other siblings. The styles mention of input_path hints at inspecting a document, but usage remains mostly 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 already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is covered. The description usefully adds that it writes one merged document with a section per record and defaults to docx, but says nothing about overwrite/collision behavior, output file naming (the 'name' default of 'merged'), or what happens on re-run for a non-idempotent write tool.

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 dense sentences with zero filler; the input modes come before the output behavior, so the agent learns what it needs first.

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?

For a 15-parameter, non-idempotent file-writing tool with no output schema, the description covers the main path but omits record-range paging, output naming/overwrite semantics, and the template_path-vs-body exclusivity — gaps an agent could get wrong on the first call.

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 80%, so the baseline is 3; the description earns an extra point by adding information the schema lacks, namely the accepted data-file formats (CSV, TSV, TXT, XLSX, ODS) and that {{Field}} placeholders map to column names. It still leaves from_record/to_record, output_path vs output_dir precedence, and template_path/body mutual exclusivity unexplained.

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+resource (merge personalized letters/certificates/notices from a data file) and names the two input modes: an existing template with merge fields, or a body with {{Field}} placeholders. The output shape — one merged document with a section per record — distinguishes it behaviorally from create_document/edit_document siblings without needing to name them.

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 'either a template document ... or a body written here' clause gives real mode-selection guidance, and the enumerated data-file formats tell the agent when this tool applies. It stops short of explicit exclusions (e.g., 'use create_document for a single non-personalized document') or prerequisites about record ranges.

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 only declare the generic non-read-only, non-destructive, non-idempotent profile; the description goes further by disclosing that control=true starts a loopback-only control channel secured by a key in WordCraft's settings folder, and that this is a prerequisite for run_wordcraft_commands live=true. That is meaningful side-effect and setup information. It stops short of saying whether an already-running app instance is reused or what the return looks like.

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, zero filler, with the primary action front-loaded and the conditional control-channel detail following. Every clause carries information an agent needs.

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?

For a two-parameter tool with no output schema and only generic annotations, the description covers the risky part (the control channel and its credential) and the cross-tool dependency. Minor gaps remain: behavior with the default empty paths array, and whether opening replaces or adds to the app's current window state.

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 50%: 'paths' is documented in the schema (absolute, max 50) and is self-explanatory from its name, while 'control' has no schema description at all. The description compensates by spelling out exactly what control=true does, so both parameters end up unambiguous. It does not address the empty-default case for either parameter.

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 ('Open documents in the WordCraft desktop app') plus the intended outcome ('for manual editing'), which separates it from create_document/edit_document that produce or modify content programmatically. It also names the sibling it feeds into (run_wordcraft_commands), so an agent can place the tool in the workflow without opening a schema.

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 establishes the selection condition clearly: use this when a human should edit documents manually, and set control=true only when a subsequent run_wordcraft_commands live=true session is intended. There is no explicit when-not statement (e.g. what to use for headless edits) and no mention of what happens if paths is left empty, so guidance is strong but not exhaustive.

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?

With annotations already declaring non-read-only, idempotent and non-destructive, the description adds genuinely new behavior: a hard cap of 4 returned page images and the fact that save=true writes files named <name>_p<N>.png. It leaves the overwrite semantics of those writes unexplained, so not a 5.

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?

A single front-loaded sentence with the core action first, then return behavior, then side effects. No filler and nothing buried.

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?

For a 9-parameter tool with no output schema, the description covers return shape (up to 4 images) and file output naming, which are the highest-risk unknowns. It does not address the interaction between save, output_dir and output_path, nor what happens when more pages are requested than the cap allows, leaving meaningful 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 67%, and the schema already documents pages, scale, markup, overwrite, output_dir and output_path. The description contributes one thing beyond the schema — the output filename pattern for save=true — but says nothing about the pages/scale/markup semantics, so it is baseline-adequate rather than compensating.

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 ("Render document pages to PNG") plus the motivating purpose ("to look at them"), which an agent can understand without opening the schema. It does not explicitly distinguish itself from convert_document or extract_text, so it stops short of a 5.

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?

"To look at them" implies a visual-inspection use case, but there is no explicit statement of when to prefer this over convert_document or extract_text, and no exclusions or prerequisites. Usage is only 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 already declare destructive/non-idempotent, and the description adds real behavior: steps execute in order, step ids are tool names, parameters can reference prior step output via '$steps[N].field' (0-based), and live=true drives the app instead of a headless engine. It omits error/partial-failure semantics (stop_on_error) and overwrite behavior, which matter for a destructive batch tool.

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 core action, and the namespace enumeration earns its space by telling the agent which command prefixes exist. The trailing 'on a new document, a template or an opened file, then save' clause is slightly compressed to the point of ambiguity, but overall density is appropriate for a 16-param 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?

For a destructive, 16-param, no-output-schema batch executor the description covers execution order, step composition and live vs headless, but leaves saving/format/overwrite behavior, failure handling, and what is returned largely to the schema. Adequate, but an agent must still open the schema to know how output artifacts come back.

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?

At 63% schema coverage, the schema leaves 'steps' items essentially undocumented; the description compensates by explaining that step id is the tool name, ordering, and the $steps[N].field reference syntax, plus the live flag's meaning. It says nothing about template/open_path/formats interaction, but the core gap is covered.

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+resource ('run any of WordCraft's 615 engine commands in order') and enumerates the command namespaces and engine tools that can be used as steps. The 'Advanced:' framing and the inclusion of engine tool names (open_document, render_page, save_document) implicitly position it against siblings, but it never names a sibling tool directly.

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?

'Advanced:' signals this is an escape hatch, and the live=true sentence gives one mode-switch condition. However, there is no explicit 'use X instead for simple edits' or 'do not use when' guidance, despite many siblings (edit_document, convert_document, render_pages) covering subsets of this tool.

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