Skip to main content
Glama
nuncaeslupus

doc-control

by nuncaeslupus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

layout_apply

Apply a page plan to a .docx: set section starts, breaks, page numbering, headers/footers, and two-sided or mirrored margins, with all-or-nothing validation and optional dry-run preview.

Instructions

Bring the document to a page plan (as layout.get returns it): where each section starts (from), its break (nextPage, oddPage for a right-hand start, evenPage, continuous), the page-number start and format, a different first page, the header and footer text per kind (default, first, even; {PAGE}, {NUMPAGES} and {chapter} become fields; null drops the section's own, so it inherits the previous section's; asking the text a section already prints changes nothing; a new part or a dropped reference that would change what a later section inheriting it prints is refused, as changing a header or footer that later sections inherit is not supported yet), two_sided (even and odd headers) and mirror_margins. Keys left out stay as they are; shown is checked, not set. Breaks, numbering and the text of a header or footer part are tracked changes; a part is rewritten only when every section using it asks the same text, else the section gets a new part. A new part, a dropped reference and two_sided or mirror_margins cannot be tracked and need untracked: true (LAYOUT D-L2). Sections already in the document must all be kept. A section that still holds an unaccepted tracked change of its setup (say from an earlier layout.apply) cannot take another, so a second apply that changes it is refused (UNSUPPORTED_CONTENT) until that change is accepted or rejected. A split-off section keeps the number format of the section it came from unless the plan states one. All or nothing: the plan read back from the result must equal the request, else nothing is written (UNSUPPORTED_CONTENT). dry_run lists the changes and the plan that would result.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
docYesPath to the .docx.
tagNoAppended to the author.
planYesThe page plan: version 1 and sections, each with a from address.
authorNoRevision author.
expectNo
dry_runNoPreview only; write nothing.
untrackedNoAllow a change Word cannot track (LAYOUT D-L2).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.4/5.0
Behavior5/5

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

Annotations carry only readOnlyHint=false, so the description bears the full burden and delivers: tracked-change semantics, the all-or-nothing write contract (result plan must equal the request or nothing is written), refusal modes (UNSUPPORTED_CONTENT for pending tracked changes), inheritance rules for headers/footers, and untracked-only operations. This is unusually rich behavioral disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The size is defensible for a genuinely complex tool, but structure is poor: a single overloaded first sentence followed by long nested parentheticals makes the constraints hard to parse. It is front-loaded in intent but buries key rules (tracking, refusal) mid-parenthesis.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter mutation tool with no output schema, the description covers refusals, tracking constraints, inheritance, and the all-or-nothing guarantee, which is substantial. It stops short of confirming exactly what dry_run returns or the success response shape, a minor gap given no output schema exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 86%, so the baseline is 3, but the description adds real semantic meaning beyond the schema: {PAGE}, {NUMPAGES}, {chapter} become fields, null drops a section's own header/footer to inherit the previous one, break types are enumerated, and dry_run's listing behavior. This meaningfully deepens the plan and untracked semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — bring the document to a page plan — and anchors the format to a sibling ('as layout.get returns it'), which cleanly separates this write tool from layout_get. An agent can identify it without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear operational context: omitted keys are left unchanged, shown keys are checked not set, dry_run previews, and untracked: true is required for changes Word cannot track. It does not spell out a clean when-not-to-use or explicitly name layout_get as the read alternative, but the conditions are well signposted.

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

Deploy Server

Other Tools