snipaya-mcp

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

Annotations already declare readOnly=false and destructive=false, so the safety profile is covered. The description adds a genuinely non-obvious behavior: ends landing on an image are anchored to it. It omits whether the new item becomes selected, what identifier is returned, and undo implications for this 7-param mutation.

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, zero filler, with the primary arrow behavior front-loaded before the variants. Slight terseness (fragmented second and third sentences) keeps it from being a model of structure, but nothing is wasted.

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

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

There is no output schema, and the description says nothing about what the call returns, whether the drawn item is selected, or how it interacts with snipaya_update_items/snipaya_undo. For a nested-object mutation with 7 parameters, the anchoring note helps but does not fully close the gap.

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 71%, and the two undocumented parameters (head and curved) are exactly the ones the description explains semantically — head true places the arrowhead at "to", head false yields a plain line, curved true bends it. It also notes anchoring semantics tied to relativeTo, adding value beyond the schema's coordinate note.

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 ("Draw a straight arrow ... or ... a line") and explains the head/curved variants. It is clearly distinguishable from shape, text, or freehand siblings, though it never names those siblings 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?

The text explains variant selection inside the tool (head false draws a line, curved true draws a curve) but gives no guidance on when to choose this over snipaya_add_shape, snipaya_add_freehand, or snipaya_add_measure. An agent must infer the boundary between arrow/line and those siblings.

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

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

Annotations already establish this is a non-destructive write, so the description's job is to add behavior, and it does: the tail defaults to below the box and the box auto-grows to fit the text, which means the resulting geometry can differ from the rect you pass. It omits whether a new item id is returned or how to subsequently modify the callout, so it's not complete.

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 zero filler, and the core visual concept is front-loaded. It is arguably too terse given the sibling set, but nothing is wasted.

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

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

For a 6-parameter mutating tool with nested objects and no output schema, the description covers the geometry behavior well but leaves gaps: no mention of the return value (an item id would be needed for snipaya_update_items), no interaction with tabId, and no note on undo. Adequate 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 83%, so the schema already documents rect, tail, style, tabId and relativeTo in detail. The description adds one genuine semantic not in the schema – that tail defaults to below the box – but says nothing about text/style/tabId/relativeTo, so 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 and resource ("Add a speech-bubble callout with text in 'rect' and a tail pointing at 'tail'") and ties the two required parameters to visible geometry, so an agent can picture the result. It doesn't explicitly contrast with add_shape or add_text, which are the nearest siblings, 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?

No when-to-use or when-not-to-use guidance. With siblings like snipaya_add_text and snipaya_add_shape present, the agent gets no instruction on when a callout is the right primitive versus a plain text box or shape, nor any precondition (e.g., must have a canvas/tab selected).

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

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

Annotations already declare this is a non-destructive, non-open-world mutation, so safety profile is covered. The description adds the useful centering detail about how 'at' anchors the sticker, but says nothing about default size, limits (size 12-400 in schema), or tab behavior beyond what the schema states.

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 compact, front-loaded sentence with no filler. It is slightly over-terse given the coordinate semantics involved, but nothing is wasted.

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

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

For a 5-parameter tool with a nested point object and no output schema, the description covers placement but omits default size, unit context, and how relativeTo interacts with coordinates beyond the schema's own text. Adequate but with clear gaps.

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

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

Schema coverage is 60% and does document 'at', 'tabId', and 'relativeTo'. The description adds the key semantic that 'at' is the CENTER of the sticker rather than a corner, which is genuinely useful; however it leaves 'size' and 'relativeTo' interplay unexplained.

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

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

States a specific verb and resource ('Place an emoji sticker') plus the placement behavior ('centered at "at"'). An agent can distinguish it from snipaya_add_text and snipaya_add_image by the emoji-sticker framing, though it never explicitly contrasts with those siblings.

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

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

There is no guidance on when to use this versus the many other add_* siblings (add_text, add_image, add_callout), nor any prerequisites or exclusions. Usage is inferable only from the tool name.

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

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

Annotations already declare this is a non-destructive, non-read-only, closed-world mutation, so the safety profile is covered. The description usefully adds that the path is smoothed like a hand-drawn stroke, but omits whether the stroke is undoable, which tab it lands on, and what (if anything) is returned so the agent can later update or select the item.

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 what is drawn, no filler or restatement of the name. Nothing to cut.

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 5-parameter mutation tool with a nested style object and no output schema, the description omits the return value entirely (no item id to feed into snipaya_update_items or snipaya_delete_items) and gives no guidance on coordinate space unless relativeTo is used. The schema compensates for styles but not for the post-call workflow.

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 60%, with the style defaults, brand colors, tabId default and relativeTo semantics all documented in the schema itself. The description adds only that the three stroke kinds exist and that the path is smoothed; it says nothing about point count limits, coordinate space, or how 'curvedArrow' differs from a plain arrow.

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 ('Draw') plus the resource types it creates (pen line, highlighter stroke, curved arrow) and the driving input ('through the given points'). It is clear what the tool does, but it never distinguishes itself from the close sibling snipaya_add_arrow, which an agent could easily confuse with the 'curvedArrow' kind here.

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 choose this over snipaya_add_arrow, snipaya_add_shape or snipaya_add_step, and no prerequisites or exclusions. The only usage-adjacent hint ('Relative to' image pixels) 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?

Annotations already declare readOnly=false, destructive=false and openWorld=false, so safety is covered structurally. The description adds the tab-grouping behavior, but says nothing about precedence when both path and dataUrl are supplied, failure modes for invalid paths, or how the image lands on the canvas (returns an id?). Useful but incomplete for a mutation 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?

Three tight sentences: capability and accepted sources first, then placement semantics and the tab-grouping rule. No filler, and the most decision-relevant guidance is front-loaded.

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 3-parameter insertion tool with no output schema, the description covers the input sources and the one enum that matters. The remaining gap — mutual exclusivity of path/dataUrl and what the call returns — is minor but real.

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 33% (path documented, dataUrl limited to a regex pattern, placement limited to an enum with a default). The description compensates by explaining what placement's enum values actually mean in workflow terms, which the schema leaves as bare strings.

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 verb and resource: 'Add a screenshot or image to the canvas', with the accepted input forms (absolute file path or data URL). It does not explicitly distinguish itself from sibling inserters like snipaya_add_shape or snipaya_add_step, so it falls short of the top mark.

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 prescribes when to use placement 'add' (before/after pairs, steps of a flow) and when to use 'new-tab' (only a new, unrelated image), including a hard exclusion: 'never one tab per related image'. This is exactly the when/when-not guidance an agent needs.

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

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

Annotations declare a non-readOnly, non-destructive, closed-world mutation, so the safety profile is already covered. The description adds useful context (radius defaults to ~8% of the short side, coordinate interpretation), but says nothing about what the call returns or that added items can be edited via snipaya_update_items / reversed via snipaya_undo.

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, front-loaded with the operation and followed by the default that matters. Nothing redundant; no restating of the title.

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 with nested style/point objects and no output schema, the description covers geometry well but omits zoom behavior (enum 2/3/4, default 2) and the return value, which an agent needs to chain into snipaya_update_items.

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 71%, and the description compensates where the schema is silent: radius has min/max bounds but no default in the schema, and the description supplies the ~8% short-side default. The distinction between lens and source points is explained relationally rather than repeated verbatim.

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: adds a round magnifying lens at 'lens' that magnifies the area around 'source'. The effect is described concretely enough to distinguish it from sibling add_* tools like add_callout or add_spotlight. It stops short of naming which sibling to use for non-magnified emphasis.

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?

Implied usage only: the described effect (zoomed view of a source area) suggests when the tool is appropriate, but there is no explicit when-to-use, when-not, or alternative routing (e.g. callout vs spotlight vs magnifier).

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

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

Annotations declare this is a non-destructive mutation (readOnlyHint=false, destructiveHint=false), so the safety profile is already covered. The description usefully discloses the return value (the label) in the absence of an output schema, but says nothing about whether the item is selected afterward, whether it is undoable via snipaya_undo, or what happens if from/to fall outside the canvas.

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 the action and return value front-loaded and no redundant padding. Nothing could be removed without losing 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 five parameters, nested point objects, and no output schema, the definition covers the essentials: required endpoints, pixel semantics, and the return value. It omits how relativeTo and tabId interact (e.g., coordinates are canvas-relative when relativeTo is unset) and any note on item selection or undo, a minor gap given how thoroughly the schema documents the 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 description coverage is 100%, so from, to, style, tabId, and relativeTo are all documented in the schema already. The description only echoes that coordinates are in image pixels, which is a partial restatement of the relativeTo documentation rather than added meaning. Baseline 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?

States a specific verb (draw) and a distinct resource (a measuring line labeled with pixel length), which separates it from snipaya_add_arrow and snipaya_add_shape by outcome rather than shape. It does not explicitly name the sibling alternatives, so it stops short of 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?

Usage is only implied: an agent can infer this is the tool for measuring distances on the canvas. There is no statement of when to prefer it over snipaya_add_arrow, nor any preconditions such as needing an image loaded via snipaya_get_canvas before using relativeTo.

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

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

Annotations already declare a non-destructive mutation, so the safety profile is covered. The description adds that omitted style fields fall back to the user's current tool style and that pixelSize defaults to the Blur/Noise tool size, but it says nothing about persistence, undo interaction (snipaya_undo exists), or what happens if the region lies outside the canvas.

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: the shape enumeration and use case come first, followed by the parameter note. No filler and nothing redundant with 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?

For a 6-parameter nested-object mutation with no output schema, the description covers the operation, kind selection, and pixelSize behavior adequately. Remaining gaps are minor, since rect/relativeTo/style/tabId are documented in the schema and the tool returns no structured output to explain.

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 83%, so baseline is 3; the description earns above that by explaining pixelSize semantics ('pixelSize sets the block size; larger is coarser') and tying it to the blur/noise kinds, which the schema alone does not do. It does not add unit guidance beyond what the schema's rect/relativeTo descriptions already provide.

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 (add) plus the exact set of resources it creates — rectangle frame, ellipse, highlighter box, blur, noise — matching the enum exactly. This clearly separates it from sibling shape/text/arrow tools like snipaya_add_arrow, snipaya_add_text, and snipaya_add_callout.

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 hints at usage with 'the safest way to hide sensitive data' for noise, which implicitly compares to redaction. However, it never explicitly says when to choose this over snipaya_redact, snipaya_add_callout, or snipaya_add_spotlight, nor does it state prerequisites such as needing a tab or captured image.

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

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

Annotations declare non-readOnly, non-destructive, closed-world, so the safety profile is covered; the description adds a genuinely non-obvious behavior — that dim alters the user's global spotlight darkness setting affecting ALL spotlights, not just this one. It does not say what is returned (e.g., an item id needed for snipaya_update_items), which is the remaining gap.

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

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

Two tight sentences, effect first, parameter notes second — front-loaded with no filler. Minor awkwardness from nested quoting around "rect" and a slightly run-on second sentence.

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 5-param nested-object creation tool with no output schema, the description covers the dim side effect well but omits what the call produces (new item id) and any interaction with sibling tools like update_items/delete_items/undo. Adequate but leaves the agent guessing about the write result.

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 60% and the description clarifies the two most semantically loaded params: rect must be rect or ellipse form and dim (0-1) controls darkness globally. tabId and relativeTo are described only in the schema, and dim's range is already in the schema, so the description adds value but does not compensate for the coverage 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 concrete verb-effect and object: dim everything except a rect/ellipse to draw attention to it. That is specific enough to separate it from snipaya_redact, snipaya_add_magnifier and snipaya_add_callout, but it never names those alternatives, so differentiation is by inference rather than stated.

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

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

"To draw attention to it" implies the use case, but there is no explicit when-to-use vs when-to-pick-something-else guidance (e.g., redact for hiding, magnifier for zooming), and no prerequisites such as needing a canvas or calling snipaya_get_canvas first. Usage must be inferred.

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

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

Annotations only declare that this is a non-destructive, non-read-only, closed-world mutation, so the description must carry the rest. It adds genuinely useful context — that numbering is automatic and that size should scale with screenshot dimensions — but leaves a serious gap: it never explains how the sequence is determined (does it count existing badges on the canvas? what happens on subsequent calls, or after snipaya_delete_items?).

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 with zero waste; the core action and placement come first, and the sizing guidance follows. 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?

There is no output schema, and the tool mutates canvas state with 5 parameters including a nested style object. The description covers placement and size but omits how auto-numbering interacts with existing steps, how it responds on later calls, and whether the returned/affected item identity matters — relevant context for a numbered-sequence 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 already 80%, so the baseline is 3. The description goes beyond the schema by defining 'size' as the badge diameter and giving the scaling rule for large screenshots, and by stating that placement is centered at 'at' — both semantics not present in 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 pairs a specific verb (add) with a specific resource (auto-numbered step badge) and anchors placement at "at". The 'auto-numbered' qualifier and 'for step-by-step guides' phrase implicitly separate it from snipaya_add_text and snipaya_add_shape, but it never explicitly names those siblings as alternatives.

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?

'for step-by-step guides' implies the scenario in which this tool is appropriate, which is more than nothing. However, it gives no explicit when-not conditions and does not route the agent to snipaya_add_text or snipaya_add_shape for non-numbered annotations.

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

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

Annotations already disclose that this is a non-destructive write operation. The description adds useful behavioral detail by specifying the top-left anchor point and newline support, but it does not describe side effects, defaults, or return behavior.

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

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

The description is two short, front-loaded sentences with no wasted language. The positioning constraint is stated immediately, followed by the newline behavior.

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 annotations covering safety and the schema documenting most parameters, the description is complete enough to invoke the tool correctly. The main missing piece is sibling differentiation for selection among the many `add_*` tools.

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 the schema already documents most parameters. The description still adds meaningful semantics by clarifying that `at` is the label's top-left corner and that `text` supports `\n` newlines.

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: 'Add a text label.' It also specifies that the label's top-left corner is positioned at the `at` point. It does not explicitly differentiate this tool from sibling annotation tools such as `snipaya_add_callout`, so it falls 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?

The description does not say when to use this tool versus alternatives like `snipaya_add_callout` or `snipaya_add_shape`. It only states what the tool does, leaving selection guidance entirely implicit.

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

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

Annotations already declare a non-destructive, non-open-world mutation. The description adds little beyond that: it doesn't say whether existing positions are overwritten, whether non-image items are left untouched, or whether the action is undoable (though snipaya_undo exists as a sibling).

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 efficient sentence with the action front-loaded and no filler. It is arguably too terse given the mutation semantics, but nothing in it is wasted.

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

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

For a 3-parameter mutation tool with no output schema, the description omits what happens to items outside the reflow, gap units, and the effect on existing layout. Adequate to invoke, but incomplete for confident use.

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 low (33%), and only tabId has a schema description. The description does add meaning for layout ('row, column or grid') and gap ('optional gap'), but leaves gap units/range and the tabId default to the schema, so it only partially compensates.

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 ('lay out') plus resource ('all images of the tab') and the enumerated layout options. It clearly distinguishes itself from the add_* siblings, though it does not name an alternative for repositioning.

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 by 'all images of the tab' — there is no explicit when-to-use framing or comparison to alternatives like snipaya_update_items, which could also move items. An agent can infer intent but gets no 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is covered structurally. The description adds genuine value with 'One undo step', telling the agent the deletion is reversible in a single undo — information not present in the annotations. It stops short of noting the 500-id cap or tab-scoping behavior, so it is not a 5.

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

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

Two short sentences with zero waste, and the core operation is front-loaded before the undo caveat. Every phrase 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?

For a destructive two-parameter mutation with no output schema, the definition is minimally adequate: it names the operation, the id keying and undo behavior. It omits batch-size limits, tab targeting, and behavior for non-existent ids, which an agent would need to call it confidently at scale.

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

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

Schema description coverage is only 50%: tabId is documented in the schema, but the required 'ids' array has no schema description. The description says 'by id' but never mentions that ids is a batch array, the 1–500 item bounds, or the tabId targeting default, so it does not compensate for the coverage 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 (delete) and resource (elements, clarified as images or annotations) with the keying mechanism (by id). It does not explicitly distinguish itself from siblings like snipaya_redact or snipaya_undo, but the scope is clear enough that an agent can tell it apart from the many add_* 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?

Usage is implied by the operation (delete existing elements by id), and 'One undo step' hints at reversibility. However, there is no explicit guidance on when to use this versus snipaya_redact, snipaya_update_items, or snipaya_undo, nor any prerequisite or exclusion 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?

Annotations already mark this as non-read-only and destructive. The description adds key behavioral details beyond them: absolute paths, matching extensions, refusal to overwrite unless overwrite is true, and the difference between file-writing and response-returning 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 compact, front-loaded, and every clause carries useful information about scope, path handling, overwrite behavior, and return mode.

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 moderate-complexity export tool with annotation coverage and no output schema, the description gives enough operational context to call it correctly. Remaining parameter details are available 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 moderate at 67%, and the description adds real semantics for ids, path, format, and overwrite behavior. It does not explain tabId or beautify, but those are covered in the schema, so this is strong but not fully compensating.

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

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

The description states a specific verb and resource: export the canvas or given ids as PNG/JPG. It is clear what the tool does, but it does not explicitly differentiate itself from nearby siblings such as snipaya_export_to or snipaya_render.

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 describes the two usage modes: providing path writes a file, while omitting path returns the image in the response. It does not name alternatives or state when a sibling tool should be preferred.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the description's job is to add nuance, and it does: network uploads always require user confirmation, and the call returns a link or file path. It does not say whether an aborted confirmation raises an error or returns null.

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: what it does, the prerequisite/confirmation caveat, the return value. Output format is stated up front 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?

Covers the essentials for a destructive, open-world export tool: source of destinations, confirmation behavior, and return shape (no output schema exists, so naming the return is necessary and done). Missing only edge-case behavior on confirmation denial or upload failure.

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

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

Schema coverage is 50%; the description clarifies that 'ids' is optional and that omitting it renders the whole canvas, which is useful. tabId and beautify semantics live only in the schema, so the description does not compensate further. 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?

Specific verb+resource: renders the canvas (or given ids) as PNG and sends it to a destination. Referencing snipaya_list_destinations as the source of valid destinations sharpens the scope. It never explicitly contrasts with the sibling snipaya_export, so an agent must infer which one is the local vs remote export path.

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 a concrete prerequisite: the destination must come from snipaya_list_destinations, which is real routing guidance. It also warns that network destinations trigger a confirmation prompt. It stops short of stating when to choose this over snipaya_export.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine value beyond that by disclosing the shape of what comes back (id, position, size, original pixel size, geometry, style, text, anchors) and by stating the sequencing convention, which is not derivable from annotations or schema.

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: the first enumerates the returned state, the second delivers the ordering rule. The most actionable instruction ('Call this first') is placed at the end as a clean imperative rather than buried in prose.

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 introspection tool with one optional param and no output schema, the description carries the return-value burden and does enumerate the major payload sections. Slightly more detail on nesting (e.g., how annotations relate to images) would make it fully self-sufficient.

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 with 100% schema description coverage, so the schema already explains tabId and its active-tab default. The description reinforces tab scoping by referring to 'the active canvas' but adds no syntax, format, or fallback detail beyond the schema — baseline 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?

Names a concrete verb+resource ('Describe the open tabs and the active canvas') and enumerates exactly what state is reported (images, annotations, selection, crop), which distinguishes it from the add_*/update_items mutation siblings. The verb 'Describe' is slightly soft — an agent could momentarily read it as generating prose rather than returning structured state — but the field list resolves that.

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 first' gives explicit ordering guidance that tells the agent to anchor on this read before issuing edits. It does not name alternatives or exclusions (e.g., versus snipaya_tabs or snipaya_select), so it stops short of full when/when-not routing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value by previewing the categories of destination that come back, partially compensating for the absent output schema. It doesn't mention the empty-list case, whether ids are stable across sessions, or auth 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?

A single sentence with zero filler. The resource and its enumeration are front-loaded, and the downstream purpose ('for snipaya_export_to') closes it out.

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-parameter read-only list tool with no output schema, the description supplies the essential missing piece: what the returned entries represent and what the ids are for. What remains unstated is edge-case behavior such as an empty destination list or whether results are user-scoped, but nothing an agent needs in order to select and call it is absent.

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 and the schema is an empty object, so there is nothing to disambiguate; baseline 4 applies. The description correctly stays silent on input semantics and spends its words on the return contract instead.

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

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

Specific verb (List) plus a specific resource (export destinations) that is enumerated by category (share menu, open with app, quick save folder, uploaders, Jira, Confluence). It also states the downstream consumer, snipaya_export_to, which separates it cleanly from siblings like snipaya_export or snipaya_save_project.

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 clause 'with their ids for snipaya_export_to' tells the agent exactly when this tool is the right one: before any targeted export. That is a clear routing signal to the alternative. It stops short of an explicit ordering statement ('call this first') or any when-not guidance, so it isn't quite a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so 'Changes nothing' largely restates structured data. It adds the useful fact that the result is a hex string, but says nothing about tab targeting behavior or coordinate resolution beyond what the schema already carries.

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 compact sentence that front-loads the action and the return format, then closes with the non-mutation guarantee. 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?

For a read-only pixel probe with full schema coverage and safety annotations, the description is nearly sufficient, and it even compensates for the missing output schema by specifying the hex return. It lacks only a note on how the point maps between canvas and image modes, which the schema covers.

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

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

Schema description coverage is 100% and the nested 'at' point plus tabId and relativeTo are documented in the schema. The description only names 'at' and the output format, adding no syntax or coordinate-mode detail beyond the structured fields, so the baseline 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?

States a specific verb (read) plus resource (color of image pixel) and the exact return format (#rrggbb hex). No sibling tool reads pixel color, so an agent can distinguish it instantly from the add_*/render/export family.

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 'Changes nothing' signals this is a non-mutating inspection, but the description gives no explicit when-to-use guidance, no mention of choosing relativeTo vs canvas coordinates, and no alternates. Usage is only implied by the schema.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false. The description adds useful behavioral context: OCR runs on-device, returns lines in reading order with rects, and coordinate interpretation depends on relativeTo.

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 sentences, front-loaded with the core action, followed by scoping and coordinate semantics. Every sentence carries useful information without repetition.

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

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

The description is sufficient for an agent to understand the tool's purpose, return content, and scoping parameters. It does not cover edge cases such as no text found or multiple images, but no output schema exists and the safety profile is already covered by 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 100%, so all four parameters are already well documented in the input schema. The description reinforces that rect and imageId can limit the operation and that rect coordinates follow relativeTo, but it adds little beyond the schema's own descriptions.

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

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

The description states a specific verb and resource: on-device OCR text recognition in images. It also specifies the return shape (lines in reading order with rects) and limiting options, which clearly distinguishes it from sibling tools like render or get_canvas.

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

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

It gives clear usage context by explaining that the operation can be limited with rect and/or imageId. It does not explicitly state when not to use it or name a sibling alternative, which keeps it below a 5.

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

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

Annotations declare a non-read-only, non-destructive, non-open-world operation, and the description corroborates this by disclosing that the edit lands 'in one undo step' — a genuine reversibility guarantee not found in the annotations. It also flags face detection as on-device and states the return payload (ids and counts). It does not cover failure modes or idempotency, keeping it short of 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?

The core action is front-loaded in the first clause and every subsequent sentence carries parameter or behavior information. It is dense but slightly run-on, and the style/pixelSize explanations restate what the schema already lists, so it is not 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?

With no output schema, the description correctly states the return value (ids and counts), and it documents all defaults so a zero-argument call is safe. Missing only edge-case behavior (nothing detected, unsupported image) for a tool that mutates user images.

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 60%, and the description compensates well for the undocumented parameters: imageIds and categories get an explicit 'Defaults to every image and category' rule, and pixelSize is clarified as 'the noise block size or a coarser minimum for blur', which goes beyond the schema's terser wording. The style enum is also explained functionally (noise/blur/solid behavior).

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 opening clause names a specific verb and resource — find listed PII categories plus faces and cover them — and adds the scope details (one undo step, user's Redaction style). No sibling tool in the list performs redaction, so an agent can rule out the other 27 tools immediately.

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 defaults ('every image and category', active tab) tell the agent it can be called with no arguments, which is useful. But there is no explicit when-to-use/when-not guidance, no prerequisite or permission notes, and no statement about what happens when nothing is detected.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds useful scope ("on the tab") and clarifies that it reverses an undo, but it does not describe what happens when there is nothing to redo or what permissions are involved.

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

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

The definition is one short, front-loaded sentence with no filler or redundancy. Every word contributes to identifying the operation and its scope.

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

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

For a simple single-parameter action with complete schema coverage and annotations covering safety, the description is nearly sufficient. It could mention the no-op case, but nothing essential for a correct invocation 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 100% and the single tabId parameter is fully described as defaulting to the active tab. The description's phrase "on the tab" aligns with that but adds no syntax or format detail beyond the schema, so the baseline 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 states a specific verb ("Redo") and resource ("the last undone change on the tab"), so an agent can immediately tell what the tool does. It does not explicitly name the sibling undo tool or distinguish itself from it, which keeps it below 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?

Usage is implied by the phrase "last undone change," which pairs naturally with undo, but the description never says when to use this versus snipaya_undo or what condition must hold. There are no explicit exclusions or alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds real behavioral context the annotations lack — the return is a downscaled PNG bounded by maxSize on the longest side, and output can be restricted to specific element ids. It doesn't say what happens with invalid ids or missing elements, keeping it off 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?

Two short sentences, the return type and purpose front-loaded, with the sizing constraint second. No filler and nothing 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 read-only render tool with full annotation coverage and no output schema, the description covers what is returned, the optional element filter, and the size bound — enough to call it correctly. Minor gaps remain around defaults for maxSize and error behavior on unknown ids.

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 compensates by defining maxSize's actual behavior (downscale on the longest side) where the schema gives only numeric bounds, and by clarifying that ids narrows the render to those elements. tabId and beautify are left entirely to the schema, which does document them adequately.

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 ("Return a PNG of the canvas") plus a scoping option (only the given element ids), and the phrase "so you can see what the user sees" implicitly separates it from export-style siblings like snipaya_export. It does not name any sibling explicitly, so it stops short of the top score.

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

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

Usage is implied by "so you can see what the user sees" — this is the visual-inspection tool. But there is no explicit when-to-use/when-not guidance and no pointer to snipaya_export or snipaya_redact as alternatives for file output or hidden content.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so safety is signaled structurally. The description adds the default-save-target behavior, but it does not explain overwrite semantics or what happens to an existing file when saving without a path, which is central for a destructive write.

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 zero filler, and the default-behavior rule is front-loaded before the exception about never-saved tabs.

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 save tool with no output schema and one undocumented parameter, the description covers the common path but leaves overwrite behavior and the return/result unaddressed. Adequate but with a real gap given destructiveHint=true.

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 33%; only tabId is documented in the schema. The description compensates for 'path' by explaining absolute-path requirement and default resolution, but 'overwrite' is left completely unexplained in both schema and description.

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 ('Save the tab as a .snipaya project'), which is clearly distinguishable from the export siblings. It stops short of explicitly contrasting with snipaya_export/snipaya_export_to, but the concept 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?

The description gives useful default behavior ('Without path, saves to the tab's existing file; a tab that was never saved needs an absolute path'), which implies when a path is required. However, it never says when to choose this over export/export_to, 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?

Annotations mark this as non-read-only but non-destructive, which is odd without context; the description resolves that by disclosing the key side effect that an empty list clears the current selection. It does not say whether selection is transient UI state or persisted, which is the remaining behavioral question.

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, purpose first and the edge-case behavior second. Nothing 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 two-parameter selection tool with no output schema, this covers purpose, intent, and the clear-selection edge case. Missing only what is returned and how invalid ids are handled.

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

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

Schema coverage is 50% — tabId is documented in-schema while ids is bare. The description adds that ids are element ids and that an empty array is meaningful, but leaves the 500-item cap and id format to 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 ('Select elements by id') and adds the intent (so the user sees which ones you mean), which separates it from mutation siblings like snipaya_update_items or snipaya_delete_items. It never names a sibling explicitly, so differentiation is implied rather than stated.

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 'so the user sees which ones you mean' implies the usage context (visual highlighting during a conversation) and the empty-list case is covered. There is no guidance on when to prefer this over snipaya_update_items or snipaya_delete_items, or what happens with invalid ids.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write/non-destructive profile is covered. The description adds real value by disclosing that the crop affects exports and is reversible via null, but says nothing about persistence (save_project) or whether it affects render vs export only.

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

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

A single sentence that front-loads the action and pairs it with the reset path. Nothing 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 3-parameter mutation with no output schema, the description covers the core effect and the reset path but omits whether the crop persists to the saved project and how it interacts with per-tab scope or export destinations.

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

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

Schema coverage is 67%, with rect/tabId/relativeTo each described. The description's key contribution is explaining what null means semantically—remove the crop—which the schema's bare 'anyOf null' does not convey.

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 specific verb+resource: it sets the crop rectangle applied to exports. It clearly implies a state mutation on the canvas, though it never names the sibling tools it relates to (render, export) to sharpen the mental model.

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 tells you how to remove a crop (pass null) but not when to use this tool versus manipulating a canvas via snipaya_get_canvas or checking the result via snipaya_render. Usage is implied rather than guided.

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

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

Annotations already indicate the tool is not read-only, is destructive, and is not open-world. The description adds useful behavioral context by clarifying that closing a tab does not discard unsaved work without asking the user, directly addressing the destructive action's safety behavior.

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

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

The description is a single front-loaded sentence with no wasted words. The parenthetical about closing tabs earns its place because it adds safety context.

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 three-action tool with annotations and no output schema, the description covers the action set and close behavior but omits tabId semantics. An agent still lacks explicit guidance on supplying the tab identifier for switch and close.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It effectively maps the action enum values to new, switch, and close, but it never explains the tabId parameter or whether tabId is required for switch/close, leaving a meaningful 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?

The description names three specific operations on a concrete resource: opening a new tab, switching tabs, and closing tabs. The tab-management domain is clearly distinct from the sibling drawing/editing tools, so an agent can identify the tool's role 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?

The description implies how the action parameter selects among new, switch, and close, but it does not explicitly say when to use this tool versus alternatives, nor does it state prerequisites or exclusions. Usage is inferable from the action verbs, but the guidance is only minimum viable.

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

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

Annotations already declare it is a non-destructive mutation (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds genuinely useful context that the undone change may belong to the user rather than the agent, but says nothing about reversibility, undo depth, or what happens if the stack is empty.

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 operation front-loaded and no filler; the parenthetical clarification about ownership 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 a zero-required-parameter mutation with annotations covering the safety profile and no output schema, the description is nearly sufficient. Only the no-op/empty-stack case is left unstated.

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?

There is only one optional parameter and the schema documents it at 100% coverage ('Target tab id. Defaults to the active tab.'). The description adds no extra meaning beyond the schema, so the baseline 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?

States a specific verb (undo) and target scope (the last change on the tab), which unambiguously separates it from siblings like snipaya_redo or snipaya_delete_items. It does not explicitly name the sibling it pairs with, but the operation is self-evident.

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

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

Usage is implied by 'undo the last change' but there is no explicit when-to-use/when-not guidance, no mention of snipaya_redo as the inverse, and no stated behavior when there is nothing to undo. Adequate but leaves the agent to infer.

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

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

Annotations only declare non-read-only, non-destructive. The description adds real behavioral context the annotations cannot: the whole batch collapses into one undo step, and step badges resize via width or style.fontSize rather than width/height. It stops short of saying what happens on an unknown id or a partial-failure 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?

Two sentences, front-loaded with the operation and its full field list, then a single special-case clause. Every clause carries information an agent would otherwise have to guess.

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, yet the description never says what is returned (updated items? count? nothing) or how failures on individual ids are reported for a batch of up to 200. For an atomic multi-element mutation, that gap matters more than the internal detail that is present.

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

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

Schema coverage is 67%, with tabId and relativeTo documented inline. The description does add genuine meaning beyond the schema: rotation is in degrees, and width/fontSize behave specially on step badges. But it says nothing about the 200-item batch cap, id sourcing, or interaction between relativeTo coordinates and x/y.

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 ("Change existing elements by id") and enumerates the exact mutation surface: move, resize, rotate, text, restyle. The word "existing" plus "by id" cleanly separates it from the many snipaya_add_* siblings, which create new elements.

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 (operate on elements you already have ids for) but there is no explicit when-to-use guidance and no mention of snipaya_select or snipaya_arrange, which also reposition/style existing elements. Nothing tells the agent where ids must come from, even though snipaya_get_canvas is the obvious source.

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