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

With no annotations provided, the description carries the full burden of disclosing behavior. It clearly indicates a mutating action ('set or update'), explains the partial-update semantics ('Unspecified fields keep their current value'), and provides essential context like units ('Coordinates are in mm') and exact paper/screen dimensions. It does not mention return values or error conditions, but the key behavioral traits are well covered.

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 well-structured and front-loaded with the essential 'When to use' guidance, followed by concise lists of coordinate units, paper sizes, and screen sizes. Every sentence earns its place—there is no fluff. The use of explicit labels and line breaks makes it easily scannable for an AI agent.

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 (5 parameters, nested object, enums) and the rich schema descriptions, the tool description adds crucial context such as the tool's role in the document lifecycle, exact size mappings, and the critical 'unspecified fields keep current value' behavior. It is sufficiently complete for an agent to select and invoke the tool correctly without needing an 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?

The input schema already has 100% coverage for all parameters, so the baseline is 3. The description adds valuable semantics beyond the schema: it provides exact dimensions for each paper size and screen size, clarifies that 'coordinates are in mm', and reinforces the partial-update behavior. This enriches the meaning of the 'format', 'margins', and other parameters, warranting a 4.

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 explicitly states the tool's function: 'set or update the canvas (physical frame) of a document — format, orientation, background, margins.' This is a specific verb+resource pairing that clearly distinguishes the canvas tool from sibling tools like maket_page or maket_doc by focusing on the physical frame. The phrase 'physical frame' and the inclusion of 'when switching a doc between formats' further clarify its unique role.

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 opens with 'When to use' and provides clear scenarios: 'Call this before adding content to a fresh doc, or when switching a doc between formats.' This gives explicit guidance on timing and intent, effectively differentiating from content-adding tools. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a perfect 5.

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?

No annotations are provided, so the description carries the full burden. It discloses important side effects: set overwrites, delete removes, and tokens are injected as CSS variables into every page. It doesn't mention permissions or reversibility, but the core behavioral traits are covered.

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 compact and front-loaded: a 'When to use' sentence, a sentence on behavioral effects, then a clean four-line action table. Every sentence earns its place without filler or 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?

For a tool with no output schema and nested objects, the description covers key outputs (view returns tokens, voice, rules, context_token; list returns colour-palette preview), cross-tool requirements, and side effects. It is complete enough for an agent to invoke each action correctly.

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 schema already covers all six parameters, but the description adds semantic value by explaining the action enum in the action table, noting that name is conditionally required for view/set/delete, and giving a concrete tokens example with the CSS variable naming convention. This goes well beyond the baseline for high 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?

Clearly identifies the tool's role as managing brand style guides (chartes) and enumerates four distinct actions (list/view/set/delete). It differentiates from siblings by tying the view action to the context_token required by maket_html set/patch.

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 opens with 'When to use' and states that view is a prerequisite for charte-aware HTML edits, naming maket_html set/patch as the dependent consumer. The action table provides clear per-action descriptions, making it easy to select the right operation.

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 no annotations, the description carries the full burden. It discloses that collections are typed by JSON Schema, contain ordered members, and that rendering produces one page per member. It also explains cursor behavior and state sharing ('The human's live canvas, this cursor and the exports all share this state') and validation behavior for change_schema. It does not cover side effects of delete or all actions, but provides meaningful behavioral context.

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 well-structured with a 'When to use' intro and a bulleted list of actions. The cursor explanation is somewhat lengthy but necessary. Overall, it is organized and front-loaded, with little wasted text.

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 tool is complex (9 parameters, many actions) with no output schema and no annotations. The description gives a comprehensive overview of all actions and even notes parameter requirements for cursor, but it lacks per-action parameter details (e.g., which parameters are needed for 'create' or 'bind') and does not describe return values or outputs. This leaves gaps for an agent to correctly invoke the 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 must compensate. It does explain the semantics of the action enum values (e.g., 'cursor — read or move a bound page's preview cursor' and specifically notes 'doc + page required'). However, it does not describe other parameters like 'data', 'name', 'schema', or 'description' in detail, leaving some parameters underspecified.

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 opens with 'manage data collections used by page placeholders,' providing a specific verb and resource. The list of actions (list, view, create, etc.) clearly distinguishes this tool from siblings like maket_page and maket_canvas.

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 explicit 'When to use' heading and the description of collections (typed by JSON Schema, ordered members, page binding) give clear context for when this tool applies. It does not mention when not to use it or alternative tools, but the specificity of page placeholders makes the usage context 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?

With no annotations, the description carries the full burden of behavioral disclosure and does so thoroughly. It discloses side effects: 'new... sets it active. Previous unsaved work is lost'; deletion 'refused if it's the only document left'; export embeds assets by default and import renaming/conflict behavior; revision history stays local; current state snapshots initialize revision 1. This is rich, honest, and prevents misuse.

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 for an 8-action tool with 16 parameters. It is front-loaded with a 'When to use' paragraph, and the action table is structured with bold names and bullet-like details. No filler sentences; every line conveys operational information. It could be slightly tightened, but it earns the length.

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?

This is a complex, multi-action tool with no output schema and no annotations. The description covers every action's purpose, parameter constraints, defaults, side effects, and edge cases (e.g., single-document deletion refusal, export portability, import conflict resolution). It provides sufficient context for an agent to invoke any action correctly without referring to external documentation.

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 the baseline is 3. The description adds value beyond the schema with a concise rule: 'doc is the doc in scope for every action except list. name only appears when you need a NEW name.' It also summarizes export/import parameter semantics (include_assets, docs, output, input) and clarifies action-parameter relationships. This elevates it slightly above baseline.

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 purpose: 'Manage design documents (the workspace unit: canvas + pages + meta)' and enumerates all actions (new, list, delete, duplicate, rename, meta, export, import). The opening 'When to use' paragraph explicitly distinguishes it from sibling tools (maket_workspace, maket_page, maket_html), making its scope 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?

The description opens with explicit guidance: 'When to use: every persistent document-lifecycle operation...' and names alternatives for session-level actions, per-page edits, and content. It also provides per-action details, such as which parameters apply to which action, giving the agent clear decision rules.

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 no annotations provided, the description carries full disclosure burden and does an excellent job. It reveals OAuth flow, token restoration, read-body truncation to 3000 chars, search cap of 50, image handling (validated/optimized/thumbnailed/metadata row) vs non-image handling (untouched in <DATA_DIR>/attachments), and the 'never sends' policy for drafts.

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 well-structured: a one-sentence 'When to use' summary followed by a compact action table. Every sentence earns its place; there is no fluff or repetition. The action-table format makes the multi-action tool easy to scan.

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 explains what each action returns (search lists subject/from/date, read returns headers/truncated body/attachments listing) and where files land. It covers prerequisites, side effects, and limitations (capped results, truncated body), making the tool fully comprehensible.

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?

Although the schema already has 100% parameter coverage, the description adds cross-action context and fallback semantics (e.g., to falls back to doc.meta.emailTo, with_read defaults to false, fetch_attachment requires a prior read call). It also clarifies which parameters apply to which action, making it far more useful than schema descriptions alone.

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 opens with a specific 'When to use' statement listing exactly the operations (connect Gmail, search/read mail, download attachments, create drafts). Each action in the table has a clear verb+resource (connect, search, read, fetch_attachment, draft), distinguishing it from sibling tools like maket_pdf or maket_preview.

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 explicitly states when to use the tool and prerequisites: 'All actions except connect require an active OAuth session — call connect first.' Each action is described with its specific conditions (e.g., 'Requires with_read=true at connect time'), and the draft action clarifies that Maket never sends, so the user reviews and sends from Gmail.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It discloses failure modes (set rejects whole payload, patch rolls back individually), side-effect expectations (check has no side effects), prerequisites (context_token required with charte), layout override eligibility, and detailed compliance rules. It also explains check statuses (OK, tight, overflow, unchecked) and what triggers them, making behavior highly transparent.

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 well-structured: it leads with a 'When to use' summary, then details compliance rules, layout override, state-backed document rules, and an action table. Each section adds necessary information, though there is some redundancy with schema content (e.g., data-id requirement appears in both). Given the tool's complexity, the length is justified and the organization helps an agent parse it.

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 tool has no output schema, so the description must explain return values and behaviors. It does so thoroughly: get's format parameter (html/text), check's statuses and next steps, patch's rollback behavior, and set's validation approach. It also covers edge cases like unchecked validation and the layout-override caveats. For a tool with this many actions and rules, the description is impressively 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 all parameters are already described in detail (e.g., ops structure, html example, context_token purpose). The description adds some behavioral context (e.g., when context_token is required, layout override constraints), but most of it complements rather than meaningfully extends the schema. The baseline of 3 is appropriate because the schema does the heavy lifting and the description adds incremental 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 opens with 'read and write page HTML' and then enumerates four distinct actions (set, patch, get, check) with precise verbs and targets. This clearly identifies the resource (page HTML) and differentiates the tool's internal operations, though it doesn't explicitly contrast with sibling tools. The action table makes the tool's purpose unmistakable.

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 says 'Pick set for the initial skeleton, patch for iterative edits, get to read, check to measure overflow without writing', which gives excellent action-level usage guidance. It also implies when not to use check ('without writing'). However, it does not name alternative sibling tools (e.g., maket_page, maket_canvas) for scenarios where this tool should not be used, so it's clear but not fully complete on external alternatives.

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 no annotations, the description carries full disclosure burden. It reveals disk storage, metadata store, combined movement, delete side effects (removes file, thumbnail, and metadata row), and the auto-optimisation/thumbnail behavior on import. It also discloses the authorization mechanism (context_token rejection). This is thorough behavioral transparency.

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 dense yet perfectly scoped: a one-sentence overview, a two-step workflow explanation, and a compact bulleted action list. Every sentence adds distinct value—no filler or repetition. The structure is scannable and front-loaded with the most critical constraint (the two-step rule).

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 tool with 12 parameters and 5 operations, the description covers all actions, the critical ordering constraint, storage model, and side effects. It mentions some return behavior (context_token, listing flags). However, without an output schema, it omits details about error conditions and full response formats, which would improve completeness for an agent deciding to invoke it.

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%, and every parameter already has a detailed schema description. The tool description adds a high-level action table but no parameter-level detail beyond what the schema provides. Baseline 3 is appropriate because the schema does the heavy lifting; the description does not meaningfully compensate but also doesn't need to.

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 opens with 'manage the asset library (images)'—a specific verb and resource that clearly distinguishes this tool from sibling content tools. It then enumerates the five sub-actions (list, view, meta, import, delete) with concise definitions, making the tool's scope unmistakable.

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 the required two-step sequence for metadata writes: 'view → meta is a required two-step' and 'MUST be called before meta.' It also explains why (context_token proves the image was read). While it doesn't name sibling tools as alternatives, the asset-library scope and action table give unambiguous when-to-use guidance.

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 no annotations, the description carries the burden of disclosing behavior. It explains the tool's actions and their effect (e.g., 'topic — read one topic'), making clear it is an informational/learning resource. It does not explicitly state 'read-only', but the actions ('list', 'read', 'overview') strongly imply no side effects. Minor gap is the absence of explicit non-mutating language.

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 well-organized with a clear 'When to use' lead, a clarifying note, and a structured action list. Every sentence adds value, and the format is scannable for an agent.

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 fully covers the tool's purpose, usage context, and available actions. Since there is no output schema, but the tool is a simple informational resource, the description is sufficient for an agent to select and invoke it correctly.

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, but the description adds meaning beyond the schema by describing each action in plain language ('overview — short operating model', 'topics — list available topics'). It also clarifies the relationship between action and topic. This elevates it to 4.

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 this tool is the first call for agents entering Maket and is a source of operational guidance. It explicitly distinguishes itself from the user-facing Help document, and lists concrete actions (overview, topics, topic) that define its scope.

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 when-to-use guidance ('first call for any agent entering Maket') and clearly defines what it is not (not the user-facing Help document). It orients the agent to use this as a prerequisite for other Maket 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?

With no annotations, the description carries the transparency burden. It discloses core behaviors: rendering to SVG, injecting into page HTML, scaling with the wrapper, and idempotent replacement when dataId already exists. It also warns about header formatting syntax, providing concrete behavioral detail beyond any 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 well-structured and front-loaded with usage guidance. Each sentence adds value: when to use, behavior, idempotency, and a critical formatting tip. No redundant filler; appropriate length given the tool's 13 parameters.

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 complex tool with no output schema and high parameter count, the description covers the essential context: supported diagram types, practical use cases, behavior on repeated execution, and syntax requirements. Combined with the 100% schema descriptions, an agent has sufficient information to select and invoke the tool correctly.

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 the schema already documents all parameters. The description adds valuable context beyond the schema: the code header rule (header on its own line, not semicolon) and the scaling behavior driven by width/height. This enhances parameter understanding, though not extensively.

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?

Clearly states the tool's function: 'add a diagram to a page' and 'Renders Mermaid syntax to SVG and injects it into the page HTML.' It lists supported diagram types and distinguishes from manual SVG/nested divs, aligning with sibling 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?

Provides an explicit 'When to use' section and direct comparison: 'Pick this over manual SVG or nested divs when the thing you want is conceptually a graph.' This gives actionable guidance on selecting this tool over alternatives and implies non-graph content should use other methods.

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?

Without annotations, the description carries the full burden and discloses concrete behaviors: add sets the active page, remove is refused if it's the last page, reorder adjusts activePage, and list marks active with ●. It also delegates charte enforcement to maket_html. It does not mention return values or all edge cases, but is substantially transparent.

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 well-structured: a short 'When to use' intro, a bulleted action list, and a note about charte. It front-loads the purpose and avoids superfluous language, with each sentence contributing meaningful guidance.

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 tool with five operations and seven parameters, the description covers the operations' effects, exclusions, and cross-tool coordination with maket_html. It omits explicit return-value details for non-list actions, but the actions are straightforward and the core behavior is adequately described.

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?

Even though schema coverage is 100%, the description's action table clarifies which parameters apply to each action, which the schema does not specify per-action (e.g., add requires name and html; reorder requires from and to). This adds practical parameter semantics 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 defines the tool as managing page structure within a document, enumerates five specific actions (add, remove, rename, reorder, list), and explicitly contrasts with maket_html for content, distinguishing it from siblings.

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 begins with an explicit 'When to use' line, states that for page content one should use maket_html instead, and provides a follow-up for charte compliance, giving clear when-to-use and when-not-to-use guidance.

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 no annotations, the description discloses key behavioral traits: headless Chromium rendering at true mm size, output to EXPORTS_DIR/<doc>.pdf, inlined Charte CSS for identical fonts/tokens, and the semantics of the rows parameter. It does not explicitly mention file overwrite behavior, but the provided detail is strong.

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 well-structured with a clear 'When to use' intro, a behavior paragraph, and a bullet-like list for parameters. It is a bit longer than strictly necessary but every sentence earns its place, and critical information is front-loaded. It earns a 4, not 5, due to minor 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?

For a tool with no annotations and no output schema, the description covers purpose, alternatives, rendering details, output location, parameter meanings, and prerequisites. It is thorough and self-contained, leaving few open questions for an agent deciding how to invoke it.

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?

Although schema coverage is 100% (baseline 3), the description adds meaningful context beyond the schema: it explains DPI presets (screen/print/hd) with numeric values, and elaborates on rows values (preview/current/all/template) with practical examples like mail merge. This enriches the bare 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 explicitly states 'export a document to PDF for sharing or print' with a specific verb and resource. It also distinguishes itself from the sibling tool maket_preview by noting that for a single-page raster (PNG), maket_preview snapshot should be used instead.

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 leads with 'When to use:' and explicitly names the alternative tool (maket_preview) for a different use case. It also advises checking the cursor first with maket_collection action=cursor when using collection-bound pages, providing clear situational guidance.

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 no annotations, the description fully carries the behavioral disclosure burden. It reveals that `open` launches a browser (localhost) and `snapshot` uses headless Chromium, returns a PNG inline, and writes to a file path on disk. This covers side effects like browser launch and file output; however, it doesn't mention default export paths or potential permission requirements, so it's not exhaustive.

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 compact but information-dense: a single 'When to use' sentence plus a formatted action table. No redundant words, and the structure (overview then two bullets) makes it easy to scan. Every sentence earns its place.

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 4 parameters, no output schema, and no annotations, the description covers the tool's core functionality well, including output format for `snapshot` and the browser action for `open`. It lacks some details about edge cases, error behavior, or default output paths, but is otherwise sufficient for a preview 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 100%, so baseline is 3. The description adds value by grouping actions and clarifying which parameters apply to each (e.g., 'open — No params' and schema notes that doc/page are required for snapshot). This goes beyond the raw schema descriptions, earning a 4.

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 purpose: 'view documents outside the agent' and then details two distinct operations (`open` and `snapshot`). It uses specific verbs ('launch', 'rasterises') and resources ('live preview URL', 'single page to PNG'), making it easy to distinguish from sibling tools like `maket_pdf` or `maket_image`.

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 opens with 'When to use: view documents outside the agent,' providing a clear usage context. It also distinguishes between the two actions (`open` for browser launch, `snapshot` for PNG rendering), but does not explicitly mention when *not* to use this tool or compare it to sibling alternatives, so it falls short of a 5.

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 no annotations provided, the description fully carries disclosure. It reveals key behaviors: every mutation stores a complete validated schema + data snapshot, revisions are immutable, Mustache rendering is display-only, and editable values need explicit data-maket-bind declarations. It also details the expected_revision requirement and init behavior (revision 1).

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 well-structured, starting with 'When to use' and then a bulleted action list. The middle paragraph about Mustache binding is detailed and necessary for understanding the tool's interaction model. While not ultra-concise, it is appropriately sized for a multi-action tool with 7 parameters.

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?

Without an output schema, the description explains the result of each action in words (e.g., 'read the schema and current revision', 'list immutable revisions newest first'). It also covers the data-binding model, required bindings, and the distinction between display-only Mustache and editable values. This is comprehensive for the tool's complexity.

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?

Although the schema covers 100% of parameters, the description adds significant action-specific semantics. It explains which parameters are required for which action (e.g., patch requires patch array, revision requires revision number, update requires complete data), and clarifies that init does not use expected_revision. This goes well beyond the schema's one-line 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 opens with a specific verb and resource: 'attach durable data and immutable snapshot history to one living document.' It clearly distinguishes from siblings by stating 'Document state is separate from collections and mail merge,' and the list of nine actions (init, get, update, patch, etc.) further specifies the tool's scope.

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?

Explicit 'When to use:' heading sets context. It explains when the tool is appropriate (durable data, immutable history) and when not ('separate from collections and mail merge'), and clarifies that it does not generate or style controls. Each action's description also indicates when it is required (e.g., expected_revision for mutations).

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 no annotations provided, the description carries the full burden. It discloses the lock's blocking behavior, that list_messages returns all pending messages across docs and workspace, and that ack_messages drops the specified ids. The action-by-action semantics are clearly stated.

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 primary usage distinction, then uses a concise action-by-action table format. No superfluous sentences; every line adds needed operational detail.

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 multi-action tool without an output schema, the description covers each action's behavior, lists prerequisites, and indicates return expectations (e.g., JSON for list_messages). The alternative tool for other operations is provided, rounding out the context.

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 schema already provides 100% parameter descriptions, and the tool description reinforces action-specific parameter usage (e.g., doc required for focus/state/lock, omitted for list_messages; locked toggle behavior). This adds value by summarizing the action-to-parameter mapping, although most details exist in 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 states specifically that it handles session-level interactions with the live workspace, then enumerates six concrete actions. It also differentiates itself from the sibling maket_doc tool for persistent CRUD, making its scope unmistakable.

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 opening 'When to use' sentence defines the tool's context and explicitly directs persistent document CRUD to maket_doc. Each action is described with its trigger and expected effect, leaving no ambiguity about when to invoke it.

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