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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that the content is bundled/local and that paths are resolved relative to a docs folder, which is useful, but says nothing about error behavior for missing files or content size/format.

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

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

One sentence, front-loaded with the verb and resource, with the parenthetical supplying only the information needed to construct the argument. No waste.

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 read tool with full schema coverage and no output schema, the description covers what the tool does and where the input comes from. Only minor gaps remain (error behavior on invalid path, textual return format), which are low stakes here.

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 schema example shows the shape (guides/abba.md), but the description adds the missing semantic layer: the path is relative to the docs folder and is the exact value produced by abba_docs_search, which the schema alone 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?

States a specific verb (Read) and resource (one bundled documentation file) with explicit scope, and names the sibling abba_docs_search as the source of the path value. An agent can tell this apart from abba_docs_search and the fiji_module_* tools 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?

The description establishes the workflow context explicitly: use the path that abba_docs_search returns, resolved relative to the docs folder. It does not state when NOT to use it (e.g. for module docs vs. API reference), but the usage context is clear.

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 openWorldHint=false, so safety is covered. The description adds value beyond them: it declares the return format (matching lines with their file), that the corpus is bundled/local, and a version constraint tied to the server bundle and ABBA release.

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

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

Purpose and return shape are front-loaded, which is good, but the middle sentence ('For assistants without file access: with file access, grep...') is grammatically tangled and the closing version/bundle metadata reads like packaging notes rather than invocation guidance.

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

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

For a single-parameter read-only search with no output schema and full schema coverage, the description supplies everything needed: what is searched, what comes back, and when to avoid it. Only pagination or result-size limits are unaddressed, which is minor here.

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 parameter is documented as a case-insensitive regular expression. The description only restates 'with a regular expression', adding no syntax, anchoring, or anchoring/escaping guidance beyond the schema, so 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 (search) and resource (bundled ABBA documentation), and enumerates what the bundle contains (guides, one file per command, scripting, examples) plus the return shape (matching lines with their file). It does not name the sibling abba_docs_read, so the search-vs-read split must be inferred from 'returns matching lines'.

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-not: if the assistant has file access, grep the docs folder named in the instructions instead. That is real routing guidance. It stops short of naming the sibling tool abba_docs_read as the way to read what search finds, and the conditional sentence is phrased awkwardly.

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 structured data. The description goes beyond that by specifying the concrete consequence (the ABBA window closes, unsaved work is lost) and the surprising interaction behavior when invoked during a start. It does not cover auth, latency, or post-stop state, 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?

Roughly four tight sentences: what it does, the permission gate, the anti-pattern, and the alternative. The destructive consequence is front-loaded in the first sentence and nothing is redundant.

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

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

For a one-parameter destructive stop tool with no output schema, the description supplies everything needed to decide and to call correctly: the effect, the required user authorization, and what to use instead for non-destructive inspection.

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 parameter is fully documented in-schema as the user's quoted words. The description reinforces the gating intent ('the user explicitly asks') but adds no syntax, format, or validation detail beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Stops the Fiji this extension started') and immediately scopes the blast radius ('the ABBA window closes and unsaved work is lost'). An agent can distinguish this from read-only siblings like fiji_ui_windows_read or abba_window_picture 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?

Gives an explicit trigger ('Only when the user explicitly asks to stop or restart Fiji'), an explicit exclusion ('Never to check, wait for or speed up a start'), and names the alternatives to use instead for inspection. It even warns that a slow start is normal and that stopping mid-start restarts the whole process.

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 cover the safety profile (readOnlyHint, openWorldHint=false). The description adds real behavioral context beyond them: it captures the window even when covered or locked, always the target app and never another, window-mode-only, and is not recorded in fiji_module_script.

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 core meaning and free of filler, but the single stretched sentence with colon and clause chain is slightly hard to parse. Killable clauses: none, though phrasing could be tighter.

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 makes clear the return is a rendered picture of the window. Combined with the read-only annotations and fully documented parameter, an agent has enough to invoke it; only the relation to abba_window_view is 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?

Schema coverage is 100% and window_title is already documented (title or its start, default first ABBA window, cross-referenced to fiji_ui_windows_read). The description adds nothing about the parameter, so the baseline 3 holds.

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 artifact (a picture/screenshot) and the resource (one Fiji window or dialog), elaborated as 'as it is drawn, what the user sees in it'. It does not name or differentiate itself from the sibling abba_window_view, so an agent must infer the distinction.

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?

'Window mode only' scopes when the tool applies, and the covered/locked-screen clause hints at reliability. But it never contrasts with abba_window_view or the fiji_ui_* read tools, leaving the agent to guess which to 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 readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the description's real value is the added context: the change is view-only and not persisted in the session/script, and a session started without a window will have one created. That side effect is genuinely useful information beyond the annotations, though nothing is said about failures or invalid titles.

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 purpose is front-loaded in one sentence and the remaining sentences are short and information-dense with no filler. The fragment "Window mode only." is terse to the point of being ambiguous, which is the main structural weakness.

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 telling the agent how the result is observed (abba_window_picture) and how to obtain labels for the framed region. Six optional parameters are fully schema-documented, so nothing critical is missing, though behavior on matching no window or multiple windows is left to the schema defaults.

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 genuinely adds semantics beyond the schema's per-parameter strings: it explains what "review" and "positioning" actually render (atlas section of the current slice vs. current slice plus neighbours). It also clarifies that the window has no region names, which frames how region_mm should be interpreted.

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 first sentence states a specific verb (sets) and resource (what an ABBA window shows), then enumerates the four aspects it controls: mode, current slice, channels, and framed region. It also distinguishes itself from the sibling used for observation ("Then look with abba_window_picture"), so an agent can place it without reading 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?

It states a scope restriction ("Window mode only"), confirms it does not mutate the session or appear in fiji_module_script, and routes the agent to ABBA - Snapshot with labels when region names are needed. The when-to-use itself is only implied (change the view, then inspect with abba_window_picture) rather than stated as an explicit instruction, and "window mode" is used as unexplained jargon.

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 openWorldHint=false, so safety is covered. The description adds real behavioral value beyond that: it discloses that defaults/choices reflect the state AFTER initializers ran, that live objects are discovered, and that provenance is reported as groupId:artifactId:version.

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 purpose, then the return contents, then the id note. It is dense but every clause carries information; the parenthetical example for provided_by is slightly bulky but justified.

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

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

With no output schema, the description must carry the return-value burden, and it does reasonably well by naming the reported fields (types, labels, descriptions, defaults, choices, live objects, provided_by). It stops short of describing shape/nesting of the result, but the coverage is good for a read-only introspection 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 100% and there is a single parameter, so the schema already documents `id`. The description restates the accepted forms (class name, menu path, title, script file path) in near-identical wording to the schema, adding no new semantics.

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

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

States a specific verb (describe) and enumerates the exact resources returned: a module's inputs/outputs, the live objects filling object inputs, and the providing artifact. This clearly separates it from fiji_module_search (find) and fiji_module_run (execute).

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

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

Usage is only implied — the agent can infer this is the introspection step before running a module, but the description never says when to call it instead of fiji_module_search or fiji_module_run, nor any prerequisite. No explicit alternatives or exclusions are given.

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

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

Annotations only supply readOnlyHint=false/openWorldHint=false, and the description carries the full behavioral burden well beyond that: no dialog is shown, one-live-instance object binding, the full status taxonomy (error/canceled/ok plus logged_errors), job id and dialog states (running, blocked_by_dialog), and the multi-minute first-start download side effect. This is exactly the extra context the annotations lack.

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 sentence and the dense remainder is largely justified by the tool's complexity (status semantics, job handling, cold start). It is comma-heavy and clause-dense, so a reader must work harder than ideal, but few sentences are truly expendable.

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

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

With no output schema, the description must describe returns, and it does so thoroughly: status, outputs (objects and images), new objects, nested modules run in turn, warnings/errors, and the running-job shape. An agent has everything needed to call this correctly and interpret the 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 100%, so baseline is 3, but the description adds real meaning: the valid id forms, the JSON-object shape of inputs with a concrete example and the default-preservation rule, and the rationale for the wait_seconds ceiling (clients abort after ~60 s). That exceeds what the schema fields alone 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?

The description opens with a specific verb ('Run') and resource ('a module') and immediately enumerates the accepted id forms (command class, menu path, title, script file path). It also names siblings (fiji_objects for object binding, fiji_module_status for longer runs), so an agent can distinguish it from neighbors 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?

It gives clear operating context: the module's dialog is never opened, omitted inputs keep defaults, calls block up to wait_seconds and should be followed with fiji_module_status for longer runs. It does not, however, clarify the overlap with fiji_module_run_script, which also appears to accept a script file path, leaving a genuine when-to-use ambiguity.

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 readOnlyHint=false and openWorldHint=false; the description adds meaningful behavior beyond that - the run is recorded in fiji_module_script with its code, '#@script(record="false")' opts out for observation-only scripts, nothing is written to disk, and 'python' is Jython 2.7 not CPython. These are real traits an agent would not learn from the structured fields. Remaining gap: no explicit statement of what state a script may mutate.

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 first sentence is well front-loaded, but the paragraph is dense and runs on with implementation trivia (BdvMultislicePositionerView, MultiSlicePositioner class paths, doc paths) that competes with the core instruction. Information-rich but not tight; several clauses could be trimmed or moved to a doc reference.

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

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

For a mutation tool with no output schema, the description covers async behavior (follow a longer run with fiji_module_status), the wait_seconds constraint rationale, language caveats, and input/output declaration conventions. What an agent needs to invoke it correctly is present, though the specifics of return payload rely on the sibling fiji_module_run.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics: inputs are declared in-script with '#@' lines, an object input with one live instance is bound to it, and outputs are declared with '#@output'. This goes beyond the schema's terse per-parameter 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?

States a specific verb and resource ('Run a script given as text') and immediately anchors it to a sibling ('as fiji_module_run runs a script file'), so the agent can distinguish text-execution from file-execution without opening either schema. The scope ('same inputs, result, job id and status, nothing written to disk') sharpens the boundary further.

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 routing guidance: 'For what no command does: search the commands first,' sending the agent to fiji_module_search when a built-in command exists, and advises reading scripting/groovy-steps.md before the first script. It lacks a negative-case statement about when this tool is the wrong choice, but the alternative and prerequisites are clear.

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 openWorldHint=false, so the write capability is covered structurally. The description adds useful behavior: modules declaring record=false are excluded, and the output is a replayable script whose path doubles as its id. It does not clarify whether an existing file at 'path' is overwritten, which matters for a non-read-only 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?

The content is packed into one long, parenthetical-laden run-on sentence that is difficult to parse on first read. The purpose is buried mid-sentence rather than front-loaded, and the nested aside about record=false interrupts the main clause.

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 minimal annotation detail, so the description carries the load; it does explain what the script contains (explicit inputs, replayable) and how to use the result afterward. It remains silent on error cases, overwrite semantics, and how this differs from fiji_module_run_script, leaving gaps for a pipeline-oriented 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% with a single 'path' parameter already documented ('file to write the script to; empty returns it'). The description restates 'save it (path)' without adding format, overwrite, or default behavior 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 conveys that the tool produces a Groovy script replaying this session's successful fiji_module_run calls, which is a specific resource+outcome. However, the opening is a grammatical fragment missing a verb ('The successful fiji_module_run calls ... as a Groovy script'), making the exact action hard to parse. It does not explicitly distinguish itself from the similarly named sibling fiji_module_run_script.

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?

'Once a result is right, save it (path) to keep the pipeline' gives a timing/condition for use, and it names downstream options (run it with fiji_module_run, or headless in a fresh Fiji). But it never states when to prefer this over fiji_module_run_script or what the alternative produces, so the routing guidance is only implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the agent knows this is a safe, closed-world read operation. The description adds the semantics of the search (matching all words across multiple fields), which is useful but doesn't go beyond what annotations and schema imply. No return format or pagination details are given.

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 and matching semantics, followed by usage guidance. Efficient, with no obvious filler, though the second and third sentences are somewhat repetitive in their 'search here' phrasing.

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 read-only search tool with full schema coverage and annotations, the description covers purpose, matching behavior, and when to use it. It lacks details on result ordering or limits, but those are minor given the tool's simplicity and the absence of an output schema.

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

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

Schema coverage is 100%, and the schema description already explains the query parameter with an example. The description restates the matching logic ('contain all the words of the query') but adds no new syntax or format details beyond the schema.

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

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

States a specific verb (find/search) and resource (SciJava commands and scripts), and names the searchable fields (title, menu path, description, class). This is concrete and distinguishes it from siblings like fiji_module_describe and fiji_module_run, though it doesn't explicitly contrast with those 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?

Explicitly says 'search here before writing code' and 'search here, or grep the command docs', giving clear when-to-use guidance with alternatives. The imperative phrasing directs the agent to use this as a discovery step.

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 openWorldHint=false, so the safety profile is covered, and the description adds real behavioral context beyond that: the waiting semantics, the running/blocked_by_dialog return states, and the retention policy (last 20 finished runs kept, dialog state surfaced). It doesn't describe token/pagination or error behavior, so it is 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?

Front-loaded with the follow-vs-list distinction and dense in useful detail with no filler. The em-dash-heavy second sentence is somewhat tangled, but every clause carries information.

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

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

There is no output schema, yet the description explains the return shape well (run result, running status, blocked_by_dialog, and the run listing with titles, statuses and durations). For an async follow tool with annotations covering safety, this is nearly complete; only edge cases like error/timeout behavior are unaddressed.

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 both parameters are already documented in the schema; the description largely restates the empty-job and wait semantics rather than adding new syntax or format detail. Baseline 3 is appropriate when the schema does the heavy lifting.

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: it follows a run started by fiji_module_run, returning either the result or a status of running/blocked_by_dialog, and lists runs when job is empty. The dual mode (follow vs. list) is spelled out and it explicitly names the sibling it complements, so an agent can distinguish it from fiji_module_run 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?

Clear context: use it to follow a run started by fiji_module_run, and the wait_seconds constraint (default 30, max 40, clients abort ~60s) tells the agent when to poll again. It provides no explicit exclusions or when-not-to-use guidance, so it stops short of a 5.

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

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

Annotations already cover safety (readOnlyHint=true, openWorldHint=false), so the bar is lower, and the description adds real context: the two output shapes (per-type counts vs. objects by name) and the domain mapping that an ABBA session is a MultiSlicePositioner. It lacks detail on what a viewer/session object looks like, but the added semantics are meaningful.

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

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

Two dense sentences, front-loaded with the resource statement followed by the branch semantics. Every clause is informative, though the parenthetical omissions and the trailing ABBA sentence slightly interrupt flow.

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 one optional parameter, no output schema, and full annotation coverage, the description supplies enough to call the tool correctly in both modes. It explains what each branch returns, which compensates for the missing output schema; only object detail is left unspecified.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema by clarifying that returned objects are identified 'by the names module inputs accept,' which links the type values to the module tools. It goes slightly beyond the schema's example-based description without adding format syntax.

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 the resource precisely (live objects Fiji holds: images, viewers, sessions) and spells out the two modes of behavior. The verb is implicit rather than explicit ('list/query'), and it does not name a sibling to distinguish from, but the resource and scope are 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?

Usage is implied by the two-mode branch on the type parameter (count vs. retrieve), which tells an agent when each behavior fires. However, it never states when to reach for this tool instead of fiji_module_search or fiji_module_describe, so the agent must infer the boundary.

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 readOnlyHint=false and openWorldHint=false, so the description carries the interesting behavior: it rejects missing/ambiguous dialog titles, it does NOT emulate a button press, and it reports back whether the dialog remains visible (i.e. the close can be refused). That is substantive context beyond the structured fields. It stops short of explaining what happens on refusal or any permission requirements.

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

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

Front-loads the operation and keeps the behavioral caveats tight, with no filler. The final clause runs on awkwardly ('reports whether the dialog remains visible Only for dialogs the user asked you to close'), suggesting a missing sentence break, which costs a point.

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 one required string parameter, no output schema, and sparse annotations, this covers the essentials: what it does, which dialogs it is legal for, how it fails, and that it returns visibility state. Only the exact return shape and post-close state handling are left unspecified, which is minor at this complexity.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds matching semantics the schema does not: the title must resolve to exactly one visible dialog, and missing or ambiguous matches are rejected. That meaningfully clarifies how dialog_title is used beyond its 'from fiji_ui_dialogs_read' 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?

States a specific verb+resource ('Request the normal window-manager close action for one visible dialog') and explicitly distinguishes itself from the button-choosing sibling: 'does not choose a button'. An agent can route between fiji_ui_dialog_close and fiji_ui_dialog_respond without opening either 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 precondition: 'Only for dialogs the user asked you to close', which is a real gating rule an agent would otherwise get wrong. It also implies that button selection belongs elsewhere, but does not name fiji_ui_dialog_respond as the alternative, so it falls short of a full when/when-not routing statement.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=false. The description adds genuine behavioral detail beyond that: it refuses ambiguous or missing dialogs and never picks a button implicitly, so the agent knows failure is preferred over guessing. It does not say what happens after the click (dialog close, downstream effects), 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?

Three short sentences, front-loaded with the action and then the constraints; no wasted prose. A missing period after 'implicitly' slightly blurs the third sentence into the second, but the structure remains readable.

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 action with full schema coverage and no output schema, the description covers scope, failure modes, and the user-intent precondition. It omits the post-click consequence (whether the dialog closes or the pipeline resumes), which is the only notable missing piece.

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 both parameters are already documented and the schema even points to fiji_ui_dialogs_read as the source of dialog_title. The description adds only the qualifiers 'exact' and 'enabled' for button_text, so the schema does the heavy lifting and 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: 'Click an exact enabled button in one visible dialog.' The specificity of 'exact enabled button' and the single-dialog scope distinguishes it from siblings like fiji_ui_dialogs_read and fiji_ui_dialog_close, though those alternatives are not named.

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?

'Only for dialogs the user asked you to answer' gives a clear gating condition, and 'rejects missing or ambiguous dialogs' tells the agent when the call will fail. It stops short of naming the sibling to use for discovery (fiji_ui_dialogs_read appears only in the schema), so it is context-clear but not fully 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 cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower. The description still adds genuine behavioral context not in annotations: that a command which opened an interactive dialog blocks until it is closed, which is critical for an agent orchestrating dialog handling.

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 listing purpose is front-loaded, but the second sentence is a run-on with a missing period ('modal state A command that opened...') that reads as a grammatical collision. The operational hint earns its place; its packaging does not.

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 specifies the return shape (dialog titles, messages, buttons, modal state), and it flags the interaction with blocking commands. Adequate for a zero-param read tool, though it omits whether multiple dialogs can coexist or how unauthored dialogs appear.

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 schema coverage is 100%, so there is nothing for the description to compensate for. Baseline 4 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 ('List') and resource ('visible AWT and Swing dialogs') and enumerates what each entry contains (title, messages, buttons, modal state). It does not explicitly distinguish itself from the close sibling fiji_ui_windows_read, 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?

Usage is only implied — an agent can infer this is the inspection step before fiji_ui_dialog_respond or fiji_ui_dialog_close, but neither alternative is named nor is a when-not condition given. The second sentence hints at the blocking scenario but never says when to call this tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered by structured data. The description adds only that windows are 'visible' and that the ABBA window title starts with its atlas, which is helpful context but does not disclose anything richer (e.g. ordering, pagination, or behavior when no windows exist).

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 that front-load the primary action, with the ABBA detail following as secondary context. It is marred slightly by a missing period between 'modality' and 'The ABBA window's title', which makes the sentence run on and briefly blurs where the enumeration ends.

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, so the description carries the burden of describing return values, and it does so by naming the per-window fields (titles, classes, bounds, active state, modality). Combined with the ABBA title convention, an agent has enough to call and interpret this zero-parameter read tool, though richer detail on result ordering or empty-state behavior 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 schema takes zero parameters, so per the rubric the baseline is 4. There are no argument semantics the description could clarify, and it correctly avoids inventing any.

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

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

The description opens with a specific verb+resource: 'List visible AWT and Swing windows', and enumerates what each entry contains (titles, classes, bounds, active state, modality). It distinguishes itself implicitly from fiji_ui_dialogs_read by scoping to AWT/Swing windows, though it never names the sibling to sharpen the contrast.

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 resource scope but there is no explicit when-to-use statement, no exclusions, and no routing to alternatives such as fiji_ui_dialogs_read or abba_window_view. The ABBA title-prefix note gives a useful hint for interpreting results, but not for deciding when to call the tool.

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