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

No annotations are provided, so the description carries the burden; it does disclose the visual outcome of the created object (monospace, dark background, syntax highlighting), which is genuine behavioral context. However it says nothing about object identity/handles, whether the target board must be open, undoability, or permissions — the live-vs-file behavior only surfaces in the schema's path field.

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 short sentence with the verb and resource front-loaded and no filler. Every clause (appearance details) conveys useful 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 simple creation tool with high schema coverage and no output schema, the appearance note plus rich schema descriptions of placement and target board are largely sufficient. The main omission is what the tool returns (e.g. the created object's id) for follow-up operations.

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 80%, so x, y, page and path are already well documented in the schema. The description adds no syntax, format, or sizing guidance for 'code' or positioning, so it does not exceed the schema 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?

Specific verb 'Adds' plus a concrete resource 'code block', and it even characterizes the rendered result (monospace, dark background, syntax highlighting). It does not explicitly contrast with sibling creators like add_table or add_formula, but the resource is distinctive enough to select on.

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 statement of when to use this versus add_table, add_formula, or import_mermaid, and no prerequisites or exclusions. The agent must infer usage from the tool name and schema alone.

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, so the description carries the full burden. It discloses one genuinely valuable behavioral trait — connectors re-anchor and follow objects when moved — but says nothing about whether the connector itself is returned with an id, whether the call is undoable, permission/board-context needs, or what happens with invalid ids. Safety and mutation semantics are left entirely implicit.

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 action and behavior, with the id-provenance hint tucked into a parenthetical. Every clause earns its place and nothing is padded.

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 mutation tool with no annotations and no output schema, a single sentence is thin: the return value (does it return the new connector's id?), live-vs-file behavior, and error conditions are unaddressed. The schema does cover the trickier parameters (path, arrow, stroke, markdown), which keeps this from being inadequate, but the description should do more for a write 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 56% across 9 parameters; 'from', 'to', 'label' and 'route' have no schema descriptions. The description usefully clarifies that from/to are object ids sourced from add_shape or describe_board, which is real added meaning, but it says nothing about arrow, route, stroke, label or page.

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?

A precise verb-plus-resource statement: 'connects two objects with an arrow', plus the non-obvious property that the connector follows the objects when they move. It even names the sibling tools that supply the required ids (add_shape, describe_board), so an agent can distinguish it from add_shape or format_text 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?

Usage is implied rather than stated, but the parenthetical gives a genuine prerequisite: from/to must be object ids obtained from add_shape or describe_board. There is no when-not guidance, no mention of what to do when ids are stale or objects are on different pages, and no alternative routing (e.g. import_mermaid for bulk connectors).

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 it does disclose one meaningful trait: unsupported LaTeX produces an error rather than a silent partial render. It says nothing about what is created (an object with an id?), whether the action is undoable, or how it behaves when the target board is live versus a file — gaps that annotations would normally cover.

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, zero filler, with the core action and its rendering semantics front-loaded. Nothing is repeated from the schema.

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 high schema coverage and no output schema, the description plus schema is nearly sufficient to call the tool correctly. The remaining gap is the return value (whether an object reference is returned for later update_object/move_objects calls) and undo semantics, which matter for a document-mutating tool with no annotations.

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 83%, so x/y/page/path/color are already well documented and the baseline is 3. The description adds only a validation note about the required 'latex' parameter (unsupported input errors out) and no format or syntax guidance beyond what the schema implies.

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 ('Adds a LaTeX formula (math mode)') and adds the rendering contract ('typeset the way TeX does'), which tells an agent exactly what artifact is produced. It does not explicitly contrast with neighboring insert tools (add_code_block, import_mermaid, add_shape), so it stops short of full 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?

No when-to-use or when-not-to-use guidance: nothing says to pick this over add_code_block or import_mermaid, and no prerequisites (live board vs file, page targeting) are stated. The only conditional sentence is a failure condition ('Errors if the LaTeX is not supported'), which is behavioral, not routing 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 and does substantial work: default sizes and valid range, ratio preservation, the mono-versus-colored stroke rule with a default color, label grouping semantics, and the returned ids. The live-vs-file behavior is left to the schema's path description rather than repeated, which is reasonable but leaves a mutation's side effects only partly visible in the prose.

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 operation, then ordered by importance (source, sizing, color, label, return). Dense with parenthetical clauses but nearly every clause carries actionable information; a minor tightening of the sizing sentence would make it a 5.

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 11-parameter tool with no output schema, the description supplies the return values (image id and label_id) and surfaces the `warnings` channel for unapplicable markup. Only the live-versus-saved board side effects and permission expectations are absent, and those are partly covered in the 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?

Schema coverage is already high (82%), so the baseline is 3; the description adds genuine relational meaning beyond it — that `size` is the longest side, that it is not combinable with w/h, that a single w or h preserves the icon ratio, and that `stroke` only applies to mono icons. It does not touch x/y/page defaults, but those are documented 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?

States a specific verb and resource ('Places an icon of the library on the board') and immediately scopes it apart from sibling resources by naming the source ('an id returned by search_icons') and the follow-up action (add_connector). An agent can distinguish this from add_image, add_shape, and add_table without opening any 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?

Usage is implied rather than stated: the reader infers this is the tool for library icons and that search_icons must run first to obtain an id. There is no explicit 'when not to use' guidance or routing compared to add_image / add_shape, which matters given several visually 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?

With no annotations at all, the description carries the full disclosure burden. It does usefully add the 15 MiB cap, the allowed-root restriction and the 600px natural-size reduction with w/h override, but it says nothing about what is returned, whether the operation is undoable, or what happens when both source and data_base64 are omitted.

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 the resource, format list, size limit and input modes front-loaded; nothing is redundant or padded.

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 mutation tool with no annotations and no output schema, the description covers formats, size limits, input modes and sizing behavior, with positioning and page semantics delegated to well-described schema fields. Only the return value and no-input fallback behavior are unaccounted for.

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 63%, and the description compensates by explaining the undocumented w/h pair as overrides of the auto-reduced natural size and by clarifying that source and data_base64 are alternative image inputs. The positioning (x, y) and page parameters are left entirely to the schema, but those are already documented there.

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

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

The description gives a specific verb and resource ("Adds an image") plus the accepted formats and a hard size cap, which is far more informative than the bare name. However, it never differentiates itself from the nearest siblings such as add_icon or add_shape, so an agent must infer that an icon is not an 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 "from a file (`source` ...) or from base64 data (`data_base64`)" phrasing implies the two mutually exclusive input modes and that one of them is required despite no required params. There is still no statement of when to choose this over add_icon, nor any prerequisite about an open application or allowed root beyond a parenthetical.

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 behavioral burden. It discloses that the tool mutates state and returns a page number, but says nothing about permissions, side effects, live-board behavior, undoability, or what happens when no path is 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?

The description is extremely short and front-loaded, with each sentence conveying a distinct fact: the action and the return value. It is not verbose, though its brevity contributes to the tool's under-specification overall.

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, two parameters, and only 50% schema coverage, the description is incomplete. It omits board context, the optional live-board mode, parameter semantics, and any side-effect or permission details an agent would need before calling 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 coverage is only 50%, and the description adds no parameter meaning at all. It does not explain what "name" means or when "path" should be provided, leaving the schema to carry most of the burden for one parameter and none for the other.

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 uses a specific verb and resource: "Adds a page." It is clear what operation is performed, but it does not distinguish this tool from page-related siblings such as manage_pages or create_board.

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 gives no guidance on when to use add_page versus manage_pages, create_board, or other sibling tools. It also omits prerequisites such as whether a board must already exist or be open.

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 behavioral burden. It discloses only that the tool adds a shape and returns an id; it does not explain mutation side effects, undo behavior, live-vs-file operation, permissions, or failure modes.

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 a single front-loaded sentence with no wasted clauses. It is appropriately sized for the core purpose, though quite terse for a 12-parameter 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 mutation tool with 12 parameters, no annotations, and no output schema beyond the mention of returning an id, the description is incomplete. It lacks usage guidance, behavioral disclosure, and parameter semantics needed to call it reliably.

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 58%, leaving several parameters (h, w, text, font_size) without schema descriptions. The description only clarifies the geom enum variants and mentions text, adding minimal meaning beyond the structured 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?

States a specific verb ('Adds') and resource ('a shape with text'), enumerates the allowed geometry types, and says it returns the id. It is clearly distinguishable from sibling tools like add_connector or add_image, though it does not explicitly compare itself to 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?

There is no guidance on when to use this tool rather than alternatives such as add_connector, add_table, or add_image. Usage is only implied by the tool name and shape enumeration.

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 behavioral burden, yet it only discloses that the first row is treated as a header. It says nothing about whether the tool writes to a file or the live board, whether changes are undoable, permission needs, or what the result contains (the undo and warnings behavior lives only in schema property text).

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, no filler, with the core action front-loaded and the row/header rule immediately after. Nothing could be removed without losing meaning.

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?

Six parameters with 83% schema coverage and no output schema means the parameter layer is reasonably self-documenting, but with zero annotations the description should say more about side effects and target (file vs live board) for a content-creating mutation. Placement and page defaults are only in the schema, so the description is thin 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?

Schema coverage is already high at 83%, so the baseline is 3. The description goes beyond that by explaining that `rows` is a list of rows of cell texts and that the first row is the header — a semantic rule the schema does not encode, which materially changes how an agent builds the 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 and resource ('Adds a table of cells') plus the row shape and header-row convention, which clearly separates it from siblings like add_shape, add_code_block or add_image. It doesn't explicitly contrast with an alternative such as importing a table, so no sibling is named, but the purpose is 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?

There is no when-to-use guidance, no prerequisites, and no alternatives mentioned. An agent gets no signal about when a table beats add_shape or add_code_block, or what happens if a board is already open.

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 so substantively: locked objects are skipped by align/distribute and reported in `skipped_locked`, distribute with fewer than 3 errors instead of silently doing nothing, group requires 2+ and returns `group`, and the stacking actions mutate `z` visible via describe_board detail "full". It never states permissions, reversibility, or limits, which keeps it below 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?

Front-loaded with the operation list and compressed into a few dense sentences with no filler. The telegraphic fragments ('group (2+ objects, returns `group`), ungroup, lock, unlock.') are efficient but cost some readability.

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 16-action tool with no output schema and no annotations, the description covers preconditions, error conditions and two return fields (`skipped_locked`, `group`). It still omits the general response shape for align/stack actions and any mention of partial-success behavior, so it is strong 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?

Schema coverage is 75%, so most parameters are already documented and the baseline sits at 3. The description's real contribution is explaining the meaning of the `action` enum values (align vs distribute vs stack vs group semantics), which goes beyond the bare enum names but is not organized parameter-by-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?

Names a specific set of operations (align, distribute, stack, group, lock) on a specific resource and enumerates the action families, so an agent can distinguish this from move_objects, update_object or format_text without opening the 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?

Explicit preconditions are given per action family: align_* needs at least 2 unlocked objects, distribute_* needs at least 3 with equal gaps between the outermost, otherwise an error. It does not, however, name a sibling as the alternative for plain repositioning (move_objects) or say when not to use this tool.

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, yet it says nothing about the mutating side effects: that existing shape positions are overwritten, whether the change is undoable, or whether unconnected shapes are affected. The single sentence conveys the transformation type (layered graph with a direction) but omits the behavioral facts an agent needs before invoking a write operation.

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 tightly written sentence with the action and outcome front-loaded and zero filler. It is efficient, though its brevity contributes to the missing behavioral context rather than resolving 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?

For a mutation tool with no annotations and no output schema, the description should cover side effects, scope (page vs selection vs connected subgraph), and reversibility. It covers none of these, leaving the agent to infer behavior from the sibling name arrange_objects and the schema alone.

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

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

Schema description coverage is 100%, so page, path and direction are already documented in the schema, including the live-edit/undo note for path and the TB default for direction. The description adds no parameter-level meaning beyond the schema, so the baseline of 3 applies.

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 (rearranges) and a specific target (shapes joined by connectors) plus an outcome (layered graph), which clearly separates it from positional siblings like move_objects or arrange_objects. It stops short of explicitly naming the sibling it competes with, so it is clear but not fully differentiated.

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 when-to-use guidance, no prerequisite (e.g. does it operate on the whole page or only a selection?), and no mention of alternatives such as arrange_objects or move_objects. The usage is only inferable from the noun phrase 'shapes joined by connectors'.

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: it discloses the single-undo semantics, atomic defaults and rollback behavior, both failure response shapes ({applied, failed, results} vs. an error with operation index), and the page-inheritance rule. It also specifies the reference-substitution rules precisely, including the edge cases (exact "$N.key" only, literal text stays literal, "$3.99" being misread as a reference).

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?

Purpose is front-loaded in the first clause and every sentence carries operational information. It is a dense single paragraph, though, and the substitution rules could be broken out for faster scanning; density borders on overwhelming.

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 orchestration tool with no annotations and no output schema, the description covers invocation shape, ordering, reference resolution, page inheritance, failure modes, rollback, and return values. Nothing an agent needs in order to call it correctly is missing.

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 already 100%, but the description still adds real meaning: args are the same arguments the tool normally takes except path/output/source (batch-level path applies to all), and it explains the $N.key substitution grammar with concrete examples. The page-defaulting rule is also clarified beyond the schema's "Defaults to the first."

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 — runs 1 to 200 tool calls in one request on one board as a single undo step — which no sibling tool does. It also names the scope (one board, ordered operations) that separates it from calling add_shape/add_connector individually.

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?

"Use it to build or rework a board quickly instead of one call per object" gives clear when-to-use guidance, and the closing sentence lists the tools that may not appear inside a batch (batch, create_board, save_board, board_changes, export, render). It stops short of an explicit when-not-to-use condition such as preferring direct calls for a single 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 load and does disclose meaningful traits: only user edits are reported, the agent's own changes are excluded, and the first call records a baseline rather than returning deltas. It omits whether the tool itself mutates the board and says nothing about return shape or ordering.

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 short sentences, front-loaded with purpose, then the exclusion rule, then the baseline caveat. No filler.

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 usefully names the returned change categories, which is the main thing an agent needs. It leaves the delta payload structure and the effect of the baseline call on subsequent responses implicit.

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% and the single optional path parameter is fully documented in the schema, so the baseline is 3. The description never mentions the path argument or the live-versus-file mode distinction the schema covers.

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 ('Reports what the USER changed on the board') and enumerates the change categories (added, modified, deleted). It also distinguishes itself from describe_board by scope and from the agent's own edits, so an agent can identify it without opening the 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?

Names describe_board or board_changes as the reference point for 'since your last look' and clarifies the first-call baseline behavior, giving clear context for invocation. It stops short of explicit when-not guidance (e.g., 'use find_objects instead if you need a full snapshot').

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 yet discloses only that the result is empty. It doesn't say what happens if the path already exists (overwrite/error), whether permissions are needed, where the file is written, or that the live-app path is undoable — even though that undo detail is documented in the schema, not here.

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 a useful parenthetical identifying the artifact type, and zero padding. It is efficient, though arguably terse to the point of under-specification rather than over-elaboration.

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 file-creating mutation with no annotations, no output schema, and an undocumented `name` parameter, the description is too thin. An agent can't determine return behavior, overwrite semantics, or the relationship to save_board from this text alone.

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

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

Schema coverage is only 50%: `path` is well documented but `name` has no description anywhere, and the description doesn't compensate by explaining what `name` controls (file label vs. board title). The description adds no parameter meaning 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?

States a specific verb (creates) and resource (an empty board / .inkboard file), which is unambiguous. It doesn't distinguish itself from siblings like save_board or import_mermaid, so an agent must still infer whether this is a 'new blank file' vs. a save/import operation.

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 no when-to-use guidance, no prerequisites, and never names an alternative for cases like saving an existing board (save_board) or creating pages inside a board (add_page). The only contextual hint — live editing when the app is open — lives in the schema, not the description.

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 usefully discloses a non-obvious side effect — connectors bound to deleted objects remain but detached — which is real behavioral value. However, it says nothing about irreversibility, whether deletion is undoable, permission requirements, or rate limits, leaving the most consequential traits unstated.

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 immediately followed by the batch variant and its side effect. Little waste; only the trailing 'Give `id` or `ids`' is mildly redundant with the opening.

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 tool with no annotations and no output schema, the description covers the essential call mechanics (target selection, batch limits implied by schema, connector side effect). The notable gap is the absence of any statement about reversibility or confirmation, which matters most for a delete operation.

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 75%, so `ids`, `page`, and `path` are already documented in the schema. The description restates the `id`/`ids` choice and adds the connector-detachment consequence, but adds nothing about `page` or `path` beyond what the schema says. Baseline 3 is appropriate.

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

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

The description gives a specific verb and resource ('Deletes an object') and distinguishes the single-target form from the bulk form via `ids`. No sibling tool deletes objects, so differentiation is inherent, but the wording is clear and 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 use condition is implicit in 'Give `id` or `ids`' — an agent learns which parameter form to pick, but there's no statement about when deletion is appropriate, prerequisites, or what to do instead (e.g., update_object) when removal is not wanted. Adequate but thin.

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 does disclose that live mode acts on the displayed board and is undoable with Ctrl+Z, and that `selection` is only reported in live mode. However, it never states plainly that this is a read/inspection operation, nor does it cover permission requirements or behavior on missing/invalid files.

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 core purpose before mode and detail qualifications. The parenthetical field lists are slightly crammed but each carries information an agent needs to predict output shape.

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, so the description must describe returns, and it does: brief fields, full-mode extras, table cells, and live-mode `selection`. It stops short of covering failure modes (unsupported file, page not found) or whether reading large boards is bounded.

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, but the description earns above it by detailing that `detail: "full"` adds style, font, z, group, lock, rotation, route/arrow and that tables additionally list `cells` — specifics the schema's detail description does not fully enumerate. It also clarifies the live-mode behavior tied to `path`.

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 ('Lists the pages and objects of a board') and enumerates the returned fields. It also establishes that the tool reads external diagram formats, which implicitly separates it from output-producing siblings like export or render, but it never names a sibling to differentiate itself 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?

Usage is only implied: the 'live mode' sentence hints at when the path parameter may be omitted, and the `detail: "full"` sentence hints at when to request richness. There is no explicit when-to-use/when-not guidance relative to alternatives such as find_objects or render.

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 well: it explains how connectors are handled (copied and linked, or freed if the linked object is not copied), that groups become new groups, and the shift behavior between copies. It omits permission or undo details, though the path parameter schema notes live-board undoability.

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 but front-loaded, beginning with the core action and shift behavior before detailing connector and group handling. Every sentence contributes useful information without 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?

Given 6 parameters, full schema coverage, and no output schema, the description is nearly complete: it explains the copy logic, connector/group behavior, and the shape of the return value (sources and ids with ordering). Minor gaps like page/path nuances are handled by the schema descriptions.

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 meaningful semantics beyond the schema: it clarifies that dx/dy shift each copy from the previous one, states the default for count and the 50-copy maximum, and explains the ordering of returned ids. This is genuine value on top of the structured fields.

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 precise verb-resource pair ('Copies objects') and immediately explains the core mechanics. It is clearly distinguishable from sibling tools like move_objects, arrange_objects, or delete_object, though it does not explicitly name an alternative.

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 guidance on when to use this tool versus alternatives such as add_shape, add_connector, or move_objects, nor are prerequisites or exclusions stated. The description explains behavior but leaves the agent to infer the appropriate context.

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 usefully discloses that the output format is derived from the file extension (.svg, .png, .pdf, etc.), which is real behavioral info, but says nothing about overwrite behavior, permissions, errors, or where the file lands.

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 format mapping immediately following; no wasted words.

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?

Reasonable for a 3-param tool with no output schema and no annotations, since the schema covers page/path semantics and the description covers output format. However, without an output schema the description should hint at what is returned (e.g., file path) and state the state-mutation implications of the live-board path.

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 `output` parameter has no schema description, and the description compensates well by enumerating the accepted extensions and explaining the format-selection logic. `page` and `path` are covered by the schema, so the description fills the main gap.

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

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

States a specific verb and resource ("Exports a page to a file") plus the key format dimension. It does not distinguish itself from siblings like render or save_board, so the reader must infer where this fits among export-like tools.

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 format-by-extension rule implies usage, but there is no explicit when-to-use vs alternatives (e.g., render, save_board, batch) nor any exclusions or prerequisites stated.

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 behavioral burden well: it explains conjunction semantics, what `text` searches across, how `in_region` overlap works, and the meaning of `count`, `truncated`, and `objects`. It does not explicitly state read-only status, though 'Finds' strongly implies it.

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 and front-loaded: purpose first, then filter semantics, then return shape. Every sentence adds relevant information, with no obvious filler.

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 7-parameter search tool with no output schema and no annotations, the description is largely complete: it explains the filters and the return fields. The one gap is that the `objects` summaries are defined only by reference to describe_board, so the agent may need to consult that sibling for the exact object shape.

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 already high at 86%, but the description adds meaningful semantics beyond the schema for `text` (shape text, connector labels, table cells, formula LaTeX), `regex` (alternative to text), and `in_region` (bounding-box overlap). It adds less for `page`, `path`, `type`, and `limit`, which are already mostly covered by 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 a specific verb and resource: 'Finds objects on a page' by text, regex, type, or area. It also clarifies the targeted-search nature versus reading the whole board, which distinguishes it from broader board-reading siblings like describe_board.

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

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

It clearly implies when to use the tool: for finding objects without reading the whole board. It explains that filters combine conjunctively, but it does not explicitly state when not to use it or name an alternative tool such as describe_board as a usage choice.

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 well: it discloses the return value (`changed`, count of characters whose formatting changed), the error condition when `match` is missing, and the ordering semantics of `clear: true` running before the other options apply. It omits permission or live-vs-file nuances beyond what the schema already states for `path`.

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

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

Front-loads the operation and targets, then flows into part selection, then return/error behavior. Dense but nearly every clause carries information; a slight trim of the parenthetical color list would tighten it further.

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 14-parameter mutation tool with no annotations and no output schema, the description supplies the return format, the failure mode, and the interaction order of options. It leaves the live-board vs file behavior to the `path` schema description, which is reasonable.

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 3, but the description adds genuine cross-parameter meaning the schema cannot: `match` is first-occurrence unless `all: true`, `range` is half-open over plain-text indices, the default when neither is given, and that `clear` executes before other options. `cell` applicability is also clarified (valid for a table, invalid otherwise is in 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?

States a specific verb and resource plus the exact target types: text on a shape, a connector's label, or a single table cell. It draws a clear line against siblings like update_object by describing the operation as the application's own text selection (bold, italic, underline, strike, color, highlight).

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

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

Gives concrete selection rules: choose the part with `match` (first occurrence, or every one with `all: true`) or `range` [start, end), and with neither the whole text is formatted. It does not say when to prefer this tool over update_object or add_shape, but the targeting guidance is strong.

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 usefully discloses that layout is automatic and that created object ids are returned, but it omits mutation side effects, permission requirements, and whether changes are undoable (that detail lives only in the schema's path parameter).

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. The main action and supported diagram types are front-loaded, and the return behavior is stated immediately after.

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 high schema coverage and explicit mention of returned ids help, but for a mutation tool with no annotations or output schema, the description leaves notable gaps around side effects and selection versus sibling tools. It is adequate to call correctly but not fully 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 83%, so the schema documents most parameters well. The description only echoes the mermaid content indirectly via supported diagram types and adds no further syntax or formatting guidance for the required mermaid parameter; baseline 3 is appropriate.

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 ('Adds') and resource ('Mermaid diagram'), and lists supported diagram genres plus automatic layout. The purpose is clear, but it does not explicitly differentiate this from sibling tools such as add_code_block or add_shape.

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 implies usage by naming Mermaid diagram types (flowchart/graph, stateDiagram, sequenceDiagram), but gives no explicit guidance on when to choose this over add_code_block, add_shape, or add_connector, nor any exclusions.

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 must carry the behavioral burden; it does declare 'Does not modify the board' (an explicit read-only claim) and explains the path requirement when the application is closed. However, it says nothing about result size, pagination, or whether the group listing is static/cached, which matter for an agent planning a call.

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 purpose first and the caveat in parentheses; nothing is wasted. The parenthetical duplicates schema content slightly, which keeps it from being maximally 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?

For a zero-required-parameter read tool with no output schema and no annotations, the description covers what is returned (groups, sets, icon counts) and the safety profile (does not modify the board). Only secondary details like response size or ordering are missing.

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?

Only one optional parameter and schema coverage is 100%, so the schema already explains the .inkboard path format and the live-board behavior. The description's parenthetical about needing a path when the app is closed largely restates the schema rather than adding 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?

States a specific verb and resource ('Lists the groups of the icon library') plus the concrete shape of the result (groups with their sets and icon counts). It implicitly separates itself from search_icons via 'to know what to search for', though it never names that sibling outright.

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 know what to search for' gives a clear use context: call this as a discovery step before searching for icons. There is no explicit exclusion or named alternative tool, so it stops short of a full when/when-not 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?

With no annotations, the description carries the safety burden well: it discloses that deleting a page destroys its contained objects and that the last page of a board is undeletable. It also pre-describes the list return shape (number, name, object count). It does not say whether renames/deletes are reversible or what happens if the page name is ambiguous.

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 sentences, front-loaded with the operation set, then routed to the sibling, then constraints. No filler and nothing buried at the end that an agent needs up front.

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 side effects, a hard constraint, required per-action inputs, and the list return shape — enough to invoke it safely. Minor gaps remain around ambiguity resolution and whether rename/delete return anything.

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 75%, so most parameters are already documented. The description restates the page selector (number from 1, or name) and rename's name requirement, largely duplicating schema text rather than adding new semantics such as name-resolution rules or collision handling.

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 set and resource: 'Lists, renames or deletes pages', and immediately distinguishes itself from the sibling that creates them ('add_page creates them'). An agent can tell exactly what operations this tool bundles and which sibling handles creation.

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?

Routes the creation case to add_page explicitly and states which parameters each action requires ('rename and delete need page... rename also needs name'), so action selection is clear. What's missing is guidance on when to prefer page-by-number vs page-by-name, or when to use this versus inspection tools like describe_board.

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 behavioral burden and does so meaningfully: connectors bound to moved objects follow, locked objects are moved anyway, and x/y refer to the new top-left of the group's bounding box. These are non-obvious side effects an agent would otherwise have to guess. It omits return info and whether moves are undoable when acting on a file, though the schema's path parameter covers the live-undo case.

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 sentences with no filler: the mode choice is front-loaded, the bounding-box definition follows, and the two side effects are compact clauses. Every sentence changes how an agent would call the 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 7-parameter mutation tool with no annotations and no output schema, the definition covers the risky parts: coordinate reference frame, group bounding-box behavior, connector/lock side effects. Remaining gap is only the return value and error behavior, which is minor given the fully documented parameters.

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 real meaning: it explains that x/y are the new top-left corner of the bounding box of all objects (not per-object), cross-references update_object's x/y semantics, and frames dx/dy and x/y as mutually exclusive alternatives. That resolves coordinate ambiguity the schema alone leaves implicit.

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 ('Moves objects together') with the scope of a group move, and the parenthetical ties x/y semantics to update_object's singular form, which implicitly separates it from that sibling. It doesn't explicitly contrast with arrange_objects or duplicate_objects, so differentiation is partial.

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

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

'Either relative (dx, dy) or absolute (x, y)' gives clear selection guidance between the two coordinate modes, but there is no explicit statement of when to choose this tool over update_object (single object) or arrange_objects. Usage is implied by 'objects together' rather than stated.

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 so well: it declares 'Read-only: the board, the file and the undo history are untouched', states defaults (max_px 1400, padding 24), the hard limits (16–3000 px, 4x max enlargement), and the automatic downscaling above 4 MiB surfaced via `note`. The only gap is that it never explicitly says what the returned payload looks like (image content vs. URI), which matters for a no-output-schema 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?

Purpose is front-loaded in the first clause, followed by safety, then framing modes, then decoration, then sizing. Every sentence carries distinct operational information—defaults, caps, or edge cases—with no redundant restatement of the name.

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

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

For an 8-parameter tool with a nested `region` object and no output schema, the description covers framing modes, sizing limits, file output, and read-only safety. The main missing piece is the shape of the response (how the image is returned, what `note` contains in the normal case), which matters given there is no output schema to fall back on.

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, but the description adds genuine meaning beyond the schema: `show_ids` badge placement (top-left corner, middle of arrows), that pen strokes get no id, that `region` adds no padding, and the ids-vs-region exclusivity. It stops short of explaining `page` or `path` semantics beyond what the schema already says, keeping it at a 4 rather than 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?

Opens with a specific verb and resource ('Returns a PNG picture of the board') plus scope options (whole page, region, ids). It distinguishes itself from siblings by naming what it is for ('to check your work visually') and referencing `export`, `update_object`, and `add_connector` as related tools, so an agent can separate it from export/describe_board without opening schemas.

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

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

Gives explicit when-to-use ('to check your work visually'), mutually exclusive alternatives for framing ('give either, not both' for region vs ids), and a condition for the `output` parameter ('for clients that do not display images'). The routing logic between the two framing modes is fully spelled out rather than 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?

With zero annotations the description must carry the behavioral load, and it does disclose the key traits: precondition of an existing file, live-mode-only persistence, and no-op semantics in file mode. It omits what happens if the board has no file yet (silent no-op vs error) and says nothing about return value.

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 clauses, front-loaded with the action and scope, followed by the mode caveat. Nothing is wasted and nothing is redundant.

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 zero-param, no-output-schema tool this covers the essential context an agent needs: which mode it applies to and the file prerequisite. The only gap is failure behavior when the precondition is unmet, which the agent would have to discover empirically.

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 no parameters, so per the baseline this scores 4. The description correctly spends no words on parameter syntax and instead uses the space for mode 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?

States a specific verb ('saves') and resource ('the board displayed in the application'), scoped to live mode. No sibling tool performs a save, so the agent can immediately distinguish this from mutators like update_object or export.

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 gives the enabling condition (live mode, board must already have a file) and a when-not case (no effect in file mode, since every tool already saves there). It does not name an alternative action for file-mode users, but no sibling competes for this 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 and does well: it declares 'Does not modify the board', explains the `path`-optional-when-app-open precondition, and discloses match semantics ('every word of `query` must match (case-insensitive) the icon name, its set or its group') plus the `truncated` signal for overflow. It stops short of describing result shape beyond ids or any performance/rate behavior, but the safety and matching profile is 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?

Front-loaded with the action and scale, and every clause contributes (matching rule, return value, alternatives, read-only guarantee). The parenthetical icon enumeration is the only mildly verbose element, though it does help an agent judge coverage.

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 search tool with no annotations and no output schema, the description covers what matters: what is searched, how matching works, what is returned (ids), how truncation is signalled, and the `path` precondition. Enough to invoke correctly without opening the 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?

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: the AND-of-all-words, case-insensitive matching against name/set/group is not in the schema, and it frames `group`/`set` as narrowing filters and `limit`/`truncated` as interacting. That is genuine semantic value on top of documented params.

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?

Specific verb + resource: 'Searches the built-in icon library ... by keywords', with scope quantified (~28,800 icons) and content types enumerated (AWS, Azure, Kubernetes, brands, UI symbols). It is clearly distinguished from list_icon_groups (browsing) and add_icon (consuming the returned ids).

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

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

Explicitly routes the agent to siblings: 'Returns ids to give to add_icon' and 'Use list_icon_groups to see what the library contains'. Also gives a narrowing strategy — '`group` / `set` to narrow a broad search' — for the common case of an over-broad query.

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 well: it discloses atomic validation (an error changes nothing), that type-mismatched parameters are silently ignored and reported in `avertissements`, and that locked objects remain editable. These are meaningful behavioral traits beyond a plain "update". It stops short of documenting permissions or full response shape.

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 verb and a compact semicolon-delimited field list, then the validation contract. Dense but each clause earns its place given 25 parameters; the run-on structure is the only minor readability cost.

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 25-parameter mutation tool with no output schema and no annotations, the description supplies the key behavioral contract (all-or-nothing validation, ignored params surfaced in `avertissements`, locked-object handling) and scopes object-type-specific params. It doesn't fully enumerate every parameter's effect but is adequate to call 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 64% with 25 parameters, so the description must add value, and it does: it clarifies the text/markdown literal-vs-markup interplay, the `cell`+`text` combination, connector-only fields, and that irrelevant params are ignored and surfaced in `avertissements`. This layers semantics over the schema rather than repeating it.

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 ("Modifies") and resource ("an object") and enumerates the concrete facets handled: text, position, size, colors, line style, font, lock, rotation, connector route/arrows/ends, and one table cell. This clearly scopes what the tool can mutate, though it never names the overlapping siblings (move_objects, format_text, arrange_objects) so the agent must infer partitioning.

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?

"Locked objects can still be modified here" implies a when-to-use condition vs tools that may refuse locked objects, and the type-matching rule hints at applicability. But there is no explicit statement of when to prefer this over move_objects/format_text/arrange_objects, leaving routing largely to inference.

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