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

With no annotations, the description carries the full burden. It discloses the return shape ('path and initial revision'), but says nothing about overwrite behavior for an existing file, whether the file is written to disk immediately, permission requirements, or the units used for sizing 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?

Two short sentences, front-loaded with the action and followed by the return value — no filler. It is efficient, though the brevity comes at the cost of substance rather than being genuinely tight.

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 and no annotations, and the description covers only the headline result. For a file-creating mutation tool with five undocumented parameters, missing overwrite semantics and sizing units leave the agent under-informed.

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, and it does not: none of the five parameters (path, figure_id, width, height, margin) are explained. Only a weak implied link between 'figure IR file' and the required path/figure_id fields, and the numeric defaults (182/58/4) are left uninterpreted.

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 ('Create a new figure IR file') and adds a return-value note. The action is clearly distinct from siblings like papercanvas_get, papercanvas_patch, papercanvas_layout, or papercanvas_render, though it never names them 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?

No guidance on when to use this versus papercanvas_patch or papercanvas_get, and no prerequisites stated. An agent cannot tell from the description what happens if the path already exists or which figure state is required before creating.

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 disclosure burden. It does useful work by stating 'read-only' and by explaining the output taxonomy (blocking / advisory / environment) and that suggested patches are proposed rather than applied. It does not say how expensive the multi-check sweep is, whether it renders all formats or just checks renderability, or how findings are ordered or capped.

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 no filler: the first enumerates the checks, the second defines the output contract and the read-only guarantee. The scope statement is front-loaded and every clause carries information.

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 describe returns, and it does explain the three finding classes and the presence of suggested patches. What it omits is the meaning of the 'path' input and the granularity/pagination of findings. Overall a solid but not airtight fit for a single-input diagnostic 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 coverage is 0% — the single required parameter is documented only as an untyped-in-practice string titled 'Path'. The description never clarifies what that path points to (a canvas file, a project directory, a document ID) or what forms are accepted. With a 1-param schema that tells the agent nothing, the description needed to compensate and does not.

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 names a specific verb-and-resource ('aggregated quality diagnosis') and enumerates the checks it bundles: hard validation, FC001-FC008 lint, font coverage/substitution, renderability. That distinguishes it from the narrower siblings papercanvas_lint and papercanvas_inspect. It loses a point because the object being diagnosed (the 'path') is never identified as a canvas file, document, or directory.

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?

'Aggregated' implies this is the one-shot umbrella call rather than calling lint/inspect/render separately, and 'read-only' signals it is safe to run. But there is no explicit when-to-use guidance, no statement that it should be preferred over the individual sibling tools, and no mention of prerequisites or cost before running the whole sweep.

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 and does disclose the returned payload and the meaning of hard_errors (structural problems that block render/patch), which also implies a pure read. It omits failure behavior for a bad path and says nothing about cost or whether the read is idempotent.

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 tight sentences with the payload description first and the workflow instruction second. Every clause earns its place, with no redundant restatement of the tool 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?

For a simple single-parameter read tool with no output schema and no annotations, the description provides the return shape and the key semantic of hard_errors, which is the important missing piece. The unexplained path parameter is the only substantial omission.

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% for the single required parameter 'path', and the description never mentions it. The agent cannot tell from either source whether path is a file path, a figure identifier, or a directory, which is a real gap for the only required input.

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 (read) and resource (full figure IR) and enumerates what the IR contains: nodes, edges, groups, theme, canvas. That is far more informative than a name restatement, though it does not explicitly distinguish itself from siblings like papercanvas_inspect or papercanvas_lint.

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?

"Call this before patching" gives a clear sequencing constraint that tells the agent when this tool belongs in a workflow. It stops short of naming when not to use it or how it differs from papercanvas_inspect/lint, so no exclusions or alternatives are offered.

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, and it does declare 'Read-only' plus the shape of what each mode returns (ids, kinds, labels vs geometry, style, edges, groups). It omits behavior for a nonexistent object_id, large-canvas pagination/truncation, and any permission requirements, which keeps it below 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?

One sentence, front-loaded with the primary behavior, using compact parentheticals to enumerate returned fields. Nothing is wasted and the mode split is placed before the read-only note.

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?

No output schema exists, and the description does describe both return shapes reasonably well, so the return-value burden is mostly met. The unexplained required path parameter and the absent guidance versus papercanvas_get and the mutating siblings are the remaining 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 description coverage is 0%, so the description must compensate and it only half does. object_id is given real semantics as a mode switch to full detail, but the required 'path' parameter is never explained at all — presumably a canvas file path, but the agent must guess.

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 concrete dual purpose: an inventory of all objects with ids/kinds/labels, or full detail for a single object_id including geometry, style, edges and groups. The verb+resource pairing is specific and an agent can tell what it returns. It falls short of 5 because it never contrasts itself with the sibling papercanvas_get, which by name appears to overlap heavily.

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 two modes are clearly inferred from whether object_id is supplied, which is genuine usage guidance. However there is no explicit statement of when to choose this tool over papercanvas_get, nor any prerequisite or exclusion. Usage is implied rather than directed.

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 zero annotations the description carries the full burden and delivers real behavioral facts: coordinates are committed to the IR, the revision increments by exactly 1, and cycles are hard errors. Gaps remain around whether existing positions are overwritten, permissions required, and what a revision conflict 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?

A single front-loaded sentence that packs the action, the preset options, the mutation semantics and the error condition with no filler. Every clause 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?

For an unannotated mutation tool with no output schema, the description covers effects and failure modes reasonably but omits the required `path` argument and says nothing about what comes back (updated IR, new revision value). Complete enough to attempt a call, not complete enough to call confidently.

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 0% and the schema defines no enum for `preset`, so the description's enumeration of linear-h | linear-v | layered is genuinely load-bearing information the schema lacks. However the required `path` parameter is never mentioned, leaving half the surface undocumented in both places.

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 concrete verb+resource ('Arrange nodes') and the effect ('commit the coordinates to the IR'), which separates it from read-only siblings like papercanvas_inspect and papercanvas_get. It stops short of explicitly distinguishing it from papercanvas_patch, which could plausibly also write coordinates.

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?

No when-to-use or when-not-to-use guidance, and no alternative is named despite patch/render being adjacent operations. The preset list hints at scenarios but the agent must infer that layout is the right tool after nodes are created or edited.

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 and does disclose the key traits: it is read-only, it returns findings with rule_id/severity/object_id, and 'error' severity is blocking. It omits whether checks are configurable beyond font size or how findings are ordered/limited, keeping it from 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?

Three dense sentences, front-loaded with the action and rule list, then result shape, then severity semantics and safety flag. Nothing is padded and every clause adds information.

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 read-only validator with no output schema and no annotations, the description covers the rule set, return fields, severity interpretation, and safety profile well. The only meaningful gap is parameter explanation, which matters given 0% schema coverage.

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 0%, so the description must explain the two parameters, but it never mentions `path` or `min_font_size_pt` explicitly. The font-size threshold can only be weakly inferred from the 'font size' rule name, leaving both parameters effectively undocumented.

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 ('run quality checks') and resource (canvas), and enumerates the eight checks so the agent knows exactly what is validated. It does not differentiate from sibling papercanvas_inspect, which likely overlaps in the 'structure' area, 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?

Implies usage through 'severity 'error' means fix before delivering', which tells the agent what to do with results but not when to call lint versus inspect/render. No explicit when-to-use or prerequisite guidance is given.

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 and does substantial work: atomicity, revision increment on success, no-op on failure, and the remove_edges:true side effect of remove_node. Missing are error shapes, permission requirements, and rate/size limits on the batch.

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 dense sentences, front-loaded with the atomic-batch guarantee, then operation types, then transactional semantics. No filler, and the most decision-relevant facts come 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 mutation tool with no annotations, no output schema, and a free-form operations array, the description is strong on transactional semantics but leaves the agent unable to construct an operation payload or understand what 'path' refers to. It is not sufficient on its own to 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 description coverage is 0% for all three parameters. The description rescues expected_revision with a clear concurrency rationale, but 'path' is never explained and the operations array is documented only by operation names — the shape of each operation object (fields for add_node, add_edge, etc.) remains undefined anywhere.

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 ('Apply a batch of semantic operations') and an explicit scope: a single all-or-nothing transaction. The enumeration of nine operation types makes the tool's capability concrete. It never names or contrasts with siblings such as papercanvas_create or papercanvas_layout, so an agent must infer why it would patch instead of create.

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?

'Pass expected_revision for optimistic concurrency' is a real usage hint for one parameter, and 'on failure nothing changes' implies retry safety. However, there is no guidance on when to choose this over papercanvas_create or papercanvas_layout, nor any stated prerequisites. Usage is implied rather than prescribed.

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 behavioral burden. It helpfully discloses that the operation is strictly read-only on the IR, that output files are written next to the IR, and that outputs are true vector and editable. It does not say whether existing files are overwritten, what permissions are needed, or how errors are surfaced.

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 tightly written sentences, front-loaded with the action and formats. Every clause adds information: the format list, the output location, the vector/editability guarantee, and the read-only constraint.

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 render tool with no output schema and no annotations, the description covers the core action, output location, and read-only nature. It is incomplete on the meaning of the required path parameter, overwrite behavior, and what is returned or reported to the caller.

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 for both parameters. It clarifies the formats parameter with a concrete list example, but the required path parameter is never explained beyond the indirect hint that outputs are written next to the IR.

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 a specific verb and resource: render the figure to svg/pdf/pptx. It is distinguishable from siblings like papercanvas_create or papercanvas_patch, but it does not explicitly contrast itself with them or clarify that those siblings manipulate the IR rather than export it.

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: use this when you need output files in svg, pdf, or pptx. However, there is no explicit when-to-use versus when-not-to-use guidance, no mention of prerequisites, and no routing to alternatives among the sibling tools.

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