AInotate

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

Annotations already declare non-read-only, non-destructive, non-idempotent, closed-world behavior, and the description adds substantial context beyond that: default draft writes to a temp folder, draft=false writes to the output folder plus a backup, only one file is written, inputs are not mutated, and the preview shows the first frame. This is exactly the kind of behavioral detail an agent needs before invoking a file-writing 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?

Dense but front-loaded: purpose and format first, then sibling routing, then the draft workflow, then return values. Every sentence carries distinct information with 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?

There is no output schema, and the description compensates by enumerating the return payload (path, frame count, format, size, preview). Combined with the workflow and side-effect disclosure, nothing an agent needs to call this 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 100%, so the baseline is 3, but the description adds real meaning beyond the schema for format ('APNG full color default' vs 'GIF plays everywhere: Slack, mail, Jira') and the draft flag's side effects, including the backup folder. Loop, name, and duration fields are left to the schema, which already documents them.

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 (animation from image paths, one frame per image), names the two output formats and their defaults, and explicitly distinguishes itself from the sibling make_guide. An agent can identify this tool and its output 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?

Gives an explicit when-to-use ('show a short sequence of states') and when-not ('for steps the user should read, make_guide is clearer'), plus the recommended two-step workflow: draft first, inspect the preview, then re-call with draft=false. Alternatives and conditions are fully spelled out.

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 readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is carried by structured data. The description adds genuinely useful context the annotations don't: draft writes go to a temp folder, draft=false persists to the output folder plus a backup folder, output is PNG only, and the input image is never modified. It stops short of disclosing failure behavior or how partially-valid specs are handled, so it is solid but not exhaustive.

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

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

The critical scoping and workflow guidance is front-loaded in the first two sentences, and the reference pointer (ainotate://spec) prevents the spec dump from needing to be exhaustive. The middle section is a dense run-on packed with pipes and braces that takes effort to parse, which costs a point, but essentially every clause carries operational 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 complex, spec-driven rendering tool, the definition covers the input contract, the draft/save lifecycle, coordinate units, output location, artifact type, and return contents (paths, size, warnings, legend, redactions, preview), and links to the full spec resource for depth. Nothing an agent needs 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 100%, so baseline is 3, but the description goes further by inlining the actual spec grammar (input, scale, crop with 'auto' or coords, name, marks with type/rect/label/n/color) and by stating the key unit rule that every coordinate uses one unit and scale converts to image px. That meaning is not derivable from the schema, which only points at a resource.

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+resource ('Draw marks on an existing image') and enumerates the exact mark types (steps, boxes, arrows, labels, highlights, spotlight, text, redaction). It explicitly distinguishes itself from the sibling 'shoot' (one-call web page capture) and from simple preview tools, so an agent can select it 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?

States the prerequisite condition plainly ('once you have an image and exact rects') and routes to the sources that produce them (capture_web, capture_window targets, locate, grid + zoom). It also names the alternative for the web-page case ('use shoot instead') and prescribes the draft-then-confirm workflow, covering when-not and how.

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 cover the safety profile (readOnly/idempotent/non-destructive); the description adds substantial context beyond them: required OS permissions, that absence yields a blank capture with a self-explaining error, Linux backend dependencies, that a PNG is written to the temp folder, and what is returned (path, size, preview). This is unusually rich behavioral disclosure.

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

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

Front-loaded with purpose and alternatives, then prerequisites and returns; most sentences earn their place. The trailing chaining advice ('locate elements with locate or grid + zoom and annotate with scale 1') is useful but slightly dense and less crisp than the rest.

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, yet the description still states the return surface (path, size, preview) as well as prerequisites and failure behavior, so an agent knows how to call it, what to expect back, and what to do next. Nothing material 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 description coverage is 100% and the single 'region' parameter is fully documented in the schema (formats, defaults, whole-display omission). The description only restates the whole-screen/one-region scope without adding format or coordinate semantics, 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 and resource ('Screenshot the whole screen or one region') with scope ('as the user sees it right now'), and names the siblings it differs from (capture_window, capture_web) with the distinguishing condition (overlap from other windows / exact element rects). An agent can select it without opening any other 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?

Gives an explicit positive trigger ('spans several windows or is not in any one window') and two explicit alternatives with the condition selecting each ('prefer capture_window for one app', 'capture_web for web pages'). Platform prerequisites (macOS Screen Recording, Linux mss/grim) are also stated with the failure mode.

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?

Beyond the annotations it discloses that the page loads over the network, that actions run in-page and can change state on the site (with a caution to only run user-requested actions), and that it requires ainotate[web] plus a Playwright browser verified by doctor. This is meaningful extra context, and it is consistent with readOnlyHint=false and openWorldHint=true.

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 purpose, then alternatives, then usage paths, then requirements, then return values. It is dense and slightly packed, but nearly every clause carries actionable information and nothing is redundant with structured fields.

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?

Although there is no output schema, the description spells out what is returned (PNG path in temp folder, rects in CSS px, scale to use as spec scale, missing targets with reasons, spec stub, preview with outlined rects). Nothing an agent needs to invoke and interpret the call 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%, so the baseline is 3, but the description adds integration-level semantics: the url-or-(cdp_url + page_url_contains) attach flow, the preset values, and the fact that actions execute before capture. This meaningfully complements the schema beyond field-level docs.

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+resource with scope: 'Screenshot a web page in a headless browser (Playwright) and measure named elements... so you can annotate with exact rects.' It explicitly distinguishes itself from siblings capture_window (desktop) and capture_screen (screen).

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 ('for web UIs') and when-not with named alternatives ('for desktop apps use capture_window, for what is on screen right now capture_screen'). It also disambiguates the url vs cdp_url attach paths and warns to only pass user-requested actions.

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 read-only, idempotent and non-destructive, and the description adds substantial context beyond them: platform-specific occlusion behavior (macOS hides covered windows, Windows/Linux fallback grabs the screen area), the Screen Recording permission requirement, the Accessibility permission needed for targets, and that a PNG is written to temp. The PNG artifact write is disclosed rather than hidden and is an output artifact, not a mutation of the target, so it does not contradict readOnlyHint.

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?

Dense but front-loaded: the one-line core behavior plus the sibling routing comes first, and platform caveats and return details follow. Every sentence carries information, though the targets/permission material is packed into a long clause that could be marginally tightened.

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

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

No output schema exists, and the description compensates by enumerating the return payload (path, size, window_id, rects, scale, preview). Combined with platform requirements and sibling routing, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real semantic value: it explains that targets is macOS-only, that it measures buttons and fields through Accessibility, that the named spec is {name: {element, role, nth, exact}}, and that the call returns rects plus the scale needed for the annotate spec.

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: screenshot one window by id, sourced from list_windows. It immediately distinguishes itself from siblings by name, contrasting capture_window with capture_screen (several windows) and capture_web (web pages).

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

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

Explicit when-to-use with named alternatives: 'Use it for desktop apps; capture_screen for several windows, capture_web for web pages.' It also constrains scope by noting it never moves, resizes or focuses the window, so the agent knows what side effects to expect from the call.

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/idempotent/non-destructive, and the description adds what they cannot: it reads but does not modify the clipboard, has an external dependency (wl-paste or xclip on Linux), and writes to the temp folder. These are real behavioral disclosures, though the failure behavior when the clipboard is empty is not stated.

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

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

Front-loaded with the action and destination, then the trigger, then exclusions, then caveats. Every sentence adds something an agent needs, and nothing is redundant with the empty 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?

With no output schema, the description fills the gap by naming the return values (PNG path, size, preview), which is what the agent needs to chain into annotate. Only the empty-clipboard/no-tool-installed failure mode is left 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?

Zero parameters, so the schema carries no semantics to compensate for; the baseline of 4 applies. The description usefully notes that the result is a PNG path despite there being no inputs.

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 and resource: save the clipboard image as a PNG in the temp folder. It also notes the downstream goal (annotate) and distinguishes itself from file-path handling in siblings annotate/locate.

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 trigger: 'when the user says they copied a screenshot'. It also names the alternative route ('for a file they sent, pass its path to annotate or locate directly'), which is exactly the branch an agent must decide against.

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-idempotent operation, and the description adds real substance beyond that: it writes one PNG, leaves inputs unchanged, defaults to a temp folder, and moves to the output folder only with draft=false. It also discloses the return contents (path, size, preview). It omits any note about overwriting behavior in the output/backup folder, which is the one 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?

Four tight sentences with no filler, covering what it produces, when to use it, the draft workflow, and the return. The framing leans slightly toward leading with the visual format rather than the action, 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?

With no output schema and modest annotations, the description carries the full burden and does so: it explains the output artifact, side effects on disk, the draft/save lifecycle, and the return values. An agent can invoke this correctly without further inference.

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 the schema already documents all six parameters including defaults for labels, layout, draft, and name. The description restates the label defaults and adds a useful localization hint ('pass labels in the audience's language'), but adds little otherwise, matching the baseline 3 for high-coverage schemas.

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 concrete verb and artifact: a before/after plate with two labeled images, side by side or stacked. It explicitly names the use case (showing a UI change or a fix), which cleanly separates it from siblings like annotate, grid, or preview.

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

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

It gives clear context for when to use it ('to show a UI change or a fix') and a concrete two-step workflow: draft first, check the preview, then call again with draft=false. It does not name an explicit alternative tool for comparison, so it falls short of a 5, but the usage path is unambiguous.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description goes further by naming exactly what is destroyed ('REPLACES whatever the clipboard holds'), requiring the agent to notify the user, and documenting platform/back-end support (macOS, Windows, Linux wl-copy/xclip). This is precisely the extra context annotations cannot carry.

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 the action and the destructive consequence, followed by the usage constraint and platform info. Every sentence carries information the agent needs; 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?

For a single-parameter tool with no output schema, the description covers the side effect, the user-facing obligation, the return value, and cross-platform behavior. An agent has everything required to call it correctly and warn the user.

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 single 'path' parameter is fully documented in the schema (formats, tilde expansion). The description adds no syntax or format detail beyond it, so the baseline 3 applies; the only added element ('Returns the path that was copied') concerns the result, not 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+resource ('Put an image on the system clipboard') plus the downstream intent ('paste it into Slack, Jira or mail'), which is far more than a restatement of the name. It is also distinguishable from the sibling clipboard_image, which reads the clipboard rather than writing to it.

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

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

Gives an explicit use condition ('use it only when they want to paste') and an explicit alternative ('otherwise give them the file path'), plus a procedural duty ('tell the user'). Nothing about when to reach for this tool versus an alternative is left to inference.

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/idempotentHint/destructiveHint, so the safety profile is covered; the description redundantly confirms 'changes nothing' but adds real value by describing the return payload ('ok, os, every check with its status and the exact fix for each failed one'). It stops short of runtime traits such as latency, cost, or whether browser-launching checks have side effects, so it is strong but not exhaustive.

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

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

Two sentences, both front-loaded: what is checked first, then when to call it and what comes back. No filler or repetition beyond the minor restatement of read-only 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 no output schema and no parameters, the description carries the full burden and discharges it: it names the inspected dependencies, the call conditions, and the shape of the result including per-check fixes.

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 zero parameters and the schema is empty, so there is nothing for the description to disambiguate; baseline is 4 for a parameterless tool.

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 ('Check') plus an explicit enumeration of what is inspected: Pillow, font, output folder, Playwright/browser, CDP browser, screen capture permission, window listing, OCR engines, clipboard, and mcp. No sibling tool overlaps with this diagnostic role, so an agent can distinguish it 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?

It states two concrete triggering conditions: 'Use it first when a tool fails with a missing dependency or permission' and 'before a long task on a new machine.' This is explicit when-to-use guidance rather than implied 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?

With readOnlyHint/destructiveHint already declaring safety, the description adds genuinely useful context: output goes to the temp folder, the input image is not modified, the preview IS the grid, and labels are in source image px. It also discloses the return payload (grid path and source image size), which matters because no output schema exists. Only minor gap is no mention of temp-file lifetime or cleanup.

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?

Four short sentences, front-loaded with the action and the purpose, then workflow routing, then side effects and returns. Nothing is padded, though it is dense enough that a reader must parse several clauses in one 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 two-parameter tool with no output schema, the description covers purpose, workflow placement, side effects, and return values. Nothing an agent needs in order to invoke 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 description coverage is 100%, so both parameters are already documented, and the schema already states 'Grid spacing in image px (> 0)'. The description's 'every `step` px' and 'labels in source image px' restate the same unit semantics rather than adding new meaning. 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 ('overlay a labelled coordinate grid ... on an image') with the exact granularity ('every `step` px'). It also distinguishes itself from siblings by naming the workflow: use grid when `locate` cannot read the element, then use `zoom` for the exact rect.

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 an explicit when-to-use trigger ('when locate cannot read it — icons, images, no text') and names both the precursor alternative (locate) and the follow-up tool (zoom) with the condition that selects it. An agent can route correctly without inferring anything.

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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: it reads metadata only, and on macOS window titles require Screen Recording permission — a real precondition an agent would not otherwise know.

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

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

Three dense sentences, front-loaded with the action and return shape, followed by parameter meaning and a permission caveat. Slightly run-on in the first sentence but no wasted content.

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 carries the burden of describing returns and does so: item fields, plus 'count, windows and a suggestion'. Combined with the permission note and the sibling reference, an agent has everything needed to call and consume this tool.

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

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

Schema description coverage is 100%, so the single parameter is already documented. The description restates the same case-insensitive substring semantics rather than adding format or edge-case detail, so it meets the baseline but no more.

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 ('List the visible windows') and immediately gives the return shape [{id, app, title, bounds}]. It also distinguishes itself from the sibling capture_window by naming it as the downstream consumer of 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 frames the tool's role: 'to get the id for capture_window', which tells the agent exactly why and when to call it. It stops short of stating when not to use it or what alternative to prefer for other listing needs, so it falls just below the top score.

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/idempotent/non-destructive, but the description adds real context beyond them: it runs locally on this machine (macOS Vision, Windows OCR, Tesseract), touches only the image, and defines result ordering (best match first) and ambiguity behavior. It does not discuss latency or engine-specific caveats, so not a full 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 front-loaded paragraph that leads with the purpose and then packs scope, coordinate format, ambiguity handling, backends, and failure fallback. Dense but each clause carries information; slightly overstuffed for one sentence-chunk.

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 8 parameters and no output schema, the description still tells the agent the result shape (matches with score and a preview outlining them) and the failure path. Missing only minor operational detail such as whether multiple matches come back by default when all=false.

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 meaning the schema lacks: rects are [x1,y1,x2,y2] in image px at spec scale 1, nth is 0-based in reading order, and all=true surfaces weaker matches. This meaningfully enriches interpretation of nth/within/all beyond their short schema blurbs.

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+resource ('Find visible text on an image by OCR and return its rect') and immediately scopes it to the cases where it applies (no DOM or accessibility data). It is clearly separable from siblings like grid, zoom, or capture_* tools, which are named as fallbacks.

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 when to use it (desktop captures, user screenshots), the alternative path when it fails ('If the text is not found, use grid + zoom'), and the ambiguity policy (ask the user, or pass nth/within). Both the selection condition and the failure fallback are explicit.

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, but the description adds substantial context beyond them: draft writes to a temp folder, draft=false writes to the output folder and a backup folder, PDF rendering falls back from Playwright to a Pillow page per step, and it 'writes files only'. It also enumerates return contents (file path per format, PDF backend, warnings, first-step preview).

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 purpose, then usage, workflow, backend behavior, and return shape — every sentence carries information. It is dense and clause-heavy (long run-on sentences), which costs a little readability, but there is 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 compensates by describing the return payload (paths per format, PDF backend, warnings, first-step preview). Combined with the draft/save workflow and the format defaults, an agent has everything needed to call it correctly in one or two turns.

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

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

Schema coverage is 100%, so the schema already documents name, draft, steps, title and formats; baseline would be 3. The description still adds semantics not in the schema, notably 'one image and text per step' and 'every image at its own size', and frames draft as a review-then-commit workflow.

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+resource ('Build a step-by-step guide from annotated images') plus the output formats (Markdown, HTML, PDF) and the step structure. It also explicitly differentiates from the sibling 'annotate' tool, so an agent can route correctly 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 ('after annotate when the user wants a how-to or documentation') and when-not ('for a single image just deliver the annotate output'), naming the alternative. The draft workflow ('check the preview, then call again with draft=false') is spelled out as an operational sequence.

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?

Goes beyond the annotations by disclosing the side effect ('Writes only a temp file, saves nothing to the output folder') and the return payload (temp path, warnings, preview). This usefully nuances readOnlyHint=true, which would otherwise suggest no filesystem activity at all. It stops short of describing failure modes or how warnings should be interpreted.

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 purpose, then the usage rule, then the side-effect/return disclosure. The middle clause ('so you can see why a label moved or a mark misses its element') is mildly verbose but earns its place by explaining the diagnostic value.

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 compensates by naming the return values (temp path, warnings, preview), and it points at the spec schema resource via the parameter definition. An agent has enough to invoke it and interpret the result correctly.

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

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

Schema description coverage is 100%, so both 'look' and 'spec' are already documented in the schema (including the fallback-with-warning behavior for an uninstalled look). The description adds no additional parameter meaning, 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+resource ('Debug render of an annotate spec') and enumerates exactly what it draws (marks, cyan target rects, magenta label boxes). It is immediately distinguishable from the sibling 'annotate', which produces the deliverable rather than a diagnostic 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?

Explicitly says when to reach for it ('Use it when the annotate preview looks wrong') and when not to ('it is not a deliverable'), implicitly routing normal output generation to 'annotate'. Both the trigger condition and the exclusion are 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 only declare the safety envelope (readOnlyHint=false, openWorldHint=true, destructiveHint=false). The description adds behavior beyond that: automatic redaction of emails/tokens/card numbers/password fields with solid blocks, network page loading, in-page action execution, and where artifacts land in draft vs non-draft mode. This is exactly the extra context annotations cannot carry.

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?

Dense but front-loaded: purpose and sibling routing come first, then spec contents, redaction, and the draft workflow. The spec sentence is a long parenthetical list, but every clause maps to a real caller decision, so little 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?

Despite no output schema, the description enumerates the return payload ('paths, warnings, legend, redactions, the capture's resolved rects and a preview'), and it covers prerequisites (network access, known selectors/text) plus the fallback path to sibling tools. Nothing an agent needs to invoke 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 description coverage is 100%, so baseline is 3. The description does add real value for 'spec', enumerating its contents (url or cdp_url + page_url_contains, preset, actions, marks with target) which the schema merely delegates to the ainotate://spec resource, but it says nothing extra about 'look', leaving the balance of meaning 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?

Opens with a precise verb+resource framing — 'One call from URL to annotated image: capture_web + annotate' — and immediately states the differentiator ('marks that point at elements by "target" instead of "rect"'). An agent can distinguish it from capture_web, annotate and preview 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?

Explicitly gives the when-to-use and when-not-to-use rule: use shoot 'when you know the visible text, role or selector of every element; use capture_web + annotate when you need to inspect rects first.' It also prescribes the two-step draft workflow ('check the preview, then call again with draft=false').

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/idempotent/non-destructive, and the description adds genuinely new behavior: the crop is written to the temp folder, the input image is unmodified, and the return payload is enumerated (zoom path, region, size, notes, preview). The only gap is the lifecycle of the temp file (overwritten? unique per call? cleanup?), which matters for an idempotent-hinted writer.

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 purpose is front-loaded in the first clause, followed by usage routing, a size caveat, and side effects — a logical, information-dense order with no filler. Slightly run-on as a single packed first sentence, but every clause earns its place.

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

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

With no output schema, the description compensates by listing the returned fields, and it covers side effects, prerequisites, and size limits — enough for correct invocation. It falls short of 5 only because the temp-file naming/lifetime and whether repeated calls overwrite a prior crop are unstated for a tool that writes output.

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 all six parameters — including the step default and the x1<x2 / y1<y2 constraints — are already documented in the schema; baseline 3 applies. The description reinforces the coordinate semantics ('labelled in SOURCE image px', 'spec scale 1') which is useful disambiguation against scaled previews, but adds no new per-parameter detail.

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 concrete noun phrase — an enlarged crop of a given rect with a fine grid labelled in source-image pixels — and states the concrete outcome (reading an exact rect off the preview). It implicitly separates itself from 'grid' (referenced as a prior step) and 'locate' (whose rect it verifies), so an agent can distinguish it without inspecting 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?

'Use it after grid, or to check a rect from locate' explicitly names the two sibling workflows and the ordering condition that selects this tool. It also gives a practical usage constraint ('keep regions under ~500 px wide or the labels get too dense') that prevents a bad call — this is exactly the when/when-not guidance the dimension rewards.

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