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

The annotations already declare destructiveHint=true and readOnlyHint=false, and the description reinforces this with concrete warning that some commands save, quit, or delete. It also discloses the return contract, the RESULT string or 'rc N (secondary M)' on error, plus case sensitivity of port names, which the annotations alone would not convey.

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

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

Three tight sentences, front-loaded with the core action and return contract, followed by the safety warning and then the routing hints. No filler or repetition.

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

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

There is no output schema, but the description explains both success and error return shapes, so an agent knows what to expect. Combined with annotations covering destructiveness and a fully documented 3-parameter schema, 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 coverage is 100%, so the baseline is 3. The description adds real meaning beyond the schema by explaining that the semantics of 'command' depend on the target program and by giving WORKBENCH examples such as 'getattr ...' and 'window ...', which the generic 'the command' schema text does not.

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

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

The description gives a specific verb and resource: send one ARexx command to a running program's ARexx port, and return its RESULT string. It also distinguishes itself from siblings by naming amiga_rexx for whole scripts and amiga_arexx_ports for port discovery.

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 clear routing rules: use amiga_arexx_ports to find port names and amiga_rexx for a whole ARexx script. It does not spell out when not to use this tool, for example when the agent should prefer read-only inspection instead of a command that may save, quit, or delete.

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 (readOnly, idempotent, non-destructive, closed-world), and the description's "Read-only" simply restates that. It does add value beyond annotations by disclosing the output shape ("one name per line") and the semantics of what appears in the list, which is the key behavioral detail for this 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?

Short and front-loaded, with the core action in the first clause. The middle sentence is somewhat wordy and the final "Read-only" duplicates the annotations, but neither is costly at this length.

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

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

For a zero-parameter listing tool with no output schema, the description supplies the essential return format and the meaning of the entries. It does not mention empty-result behavior or whether the list can be large, but nothing critical to invoking it 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?

The tool takes zero parameters, so the baseline is 4. The description correctly avoids inventing filter arguments and implies the listing is unfiltered and global.

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

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

The description uses a specific verb and resource ("List the public message ports") and explains that scriptable programs appear under their port names. The trailing "for amiga_arexx" hints at how the result is consumed but is too terse to sharply differentiate it from the amiga_arexx and amiga_rexx siblings.

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

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

Usage is only implied: an agent can infer this is the discovery step that produces port names to feed into amiga_arexx, but no explicit when-to-use or when-not-to-use guidance is stated. No alternative tool is named.

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 well beyond the destructiveHint annotation by disclosing the mechanism (Ctrl-C), the three-second grace period, the fallback behavior (slot freed anyway, process left running and shown as stuck), and the data-loss consequence ("loses whatever it had not saved"). That is exactly the operational detail an agent needs before invoking a destructive stop.

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, no filler: identity/scope first, then behavior with consequences, then the routing rule to the alternative. Each clause carries distinct information the agent cannot infer elsewhere.

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

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

For a destructive, non-idempotent two-parameter tool with no output schema, the definition covers what it does, the timeout/fallback path, the failure mode, data-loss risk, and the sibling alternative. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented, and the description's mention of the slot number largely restates the schema. It does implicitly contrast with ctrl_c_only by describing the default free-the-slot-after-timeout behavior, but it never names that parameter or explains the keep-the-slot trade-off directly.

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 ("Stop a command started by amiga_run") and pins down the identifier semantics ("by its slot number from amiga_slots"). It explicitly distinguishes itself from the sibling amiga_kill, so the agent can choose 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?

Names the prerequisite lineage (only commands from amiga_run) and names the alternative with its selection condition: "To stop any other task use amiga_kill." Both the when-to-use and when-not-to-use cases are covered explicitly.

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 non-read-only, non-idempotent, non-destructive and closed-world, so the safety profile is known. The description adds one genuinely useful trait beyond that: the button is always released even on error, which prevents an agent from worrying about stuck-button recovery. It says nothing about drag speed/interpolation or what a failed drag returns, so the added context is real but thin.

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

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

Three tight sentences: mechanics first, then supported use cases, then alternatives and the coordinate reference. Every clause carries information; nothing is padding or repetition of the title.

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

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

For a six-parameter, no-output-schema tool this covers mechanics, use cases, coordinate basis, failure guarantee and alternatives. Remaining gaps are minor: no statement of drag duration/step count for the via path, and no mention of what happens if coordinates fall outside the screen.

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 x1/y1/x2/y2, via and the button enum with its default. The description restates button usage and adds the coordinate-frame reference ('as in amiga_screenshot') plus the via-points path concept, but no format or range details beyond the schema, so baseline-plus 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 concrete sequence of actions (press at x1,y1, move through via points, release at x2,y2), which unambiguously identifies a mouse drag operation rather than a click or a timed input. The sibling list contains amiga_ui_click, amiga_mouse and amiga_input, and the description makes clear this is the coordinate-path drag variant.

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?

Enumerates concrete scenarios: drag and drop of icons/files, sliders and scroll bars, resizing, and Amiga menus with the right-button-title-bar procedure. It also names two alternatives with the conditions that select them (amiga_input for timed gestures, amiga_ui_menu for picking a menu item by name), so an agent can route correctly without guessing.

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 non-destructive, so the safety profile is covered; the trailing "Read-only" largely restates that. What the description adds beyond annotations is substantive: it discloses the platform-dependent payload (Pi-side sensors only on PiStorm/Emu68) and, importantly, that the crash report only covers the period since the Amiga booted, which is a real scoping caveat not expressible in annotations.

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 platform-specific payloads, then the usage trigger and safety note. It is long and list-dense in the middle, and the closing "Read-only" duplicates the annotations, but no sentence is genuinely wasted given the breadth of what is returned.

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 parameters and no output schema, the description carries the full burden of telling the agent what comes back, and it does so concretely for both hardware variants, including the boot-scoped caveat on the guru meditation record. An agent can decide to call it and interpret the result without further documentation.

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, so there is no parameter meaning to add; the baseline of 4 applies. The description instead spends its words on what the parameterless call returns, which is the useful thing here.

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 ("Report the machine's health") and then enumerates exactly what is reported, split by platform: PiStorm/Emu68 (temperature, voltages, clocks, under-voltage, throttling, 68k speed, JIT cache) versus every Amiga (free chip/fast memory with largest blocks, last guru meditation code). This is far more specific than any sibling such as amiga_info or amiga_ps, so an agent can distinguish 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?

Gives explicit triggering conditions: "when the machine seems slow or after a crash." That is clear context for selection, but it names no alternative tool, so an agent cannot tell from this text whether amiga_info, amiga_ps, or amiga_slots would be a better first call for a given symptom.

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, so the 'Read-only' restatement adds nothing; however, with no output schema the description's enumeration of returned fields (versions, memory, volumes, supported commands) is genuine behavioral disclosure not carried by any structured field. Minor gaps remain on formatting or failure behavior if the daemon is unreachable, but the core disclosure is strong.

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, followed by the return inventory and then the routing advice — a sensible order. The long comma-separated field enumeration and the redundant 'Read-only' clause cost a little, but each sentence contributes 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 zero-parameter, read-only introspection tool with no output schema, the description supplies everything an agent needs: what it returns, why to call it first (volume names, machine identity), and where to go for the metrics it does not cover. 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?

The tool takes zero parameters and the schema is an empty object, so there is nothing for the description to disambiguate — the baseline of 4 applies. The description correctly implies a no-argument call and focuses on return content instead.

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

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

States a specific verb+resource ("Describe the Amiga") and then enumerates exactly what is reported: Kickstart/Workbench versions, CPU, chip and fast memory, mounted volumes with sizes, and the daemon's 'can:' line. It is clearly distinguishable from siblings like amiga_health and amiga_ls 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 prescribes ordering ("Call it first to learn which machine you are on and which volume names exist") and names the alternative plus the condition that selects it ("For temperatures, CPU load and the last crash use amiga_health instead"). Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare a non-read-only, non-idempotent, non-destructive, closed-world operation, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the tick granularity (1/50 s), the hard constraint 'At most 5 s of waits in total', and the atomic one-request nature of the gesture. It stops short of saying which window receives input or what happens when the wait budget is exceeded, which keeps it from a 5.

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

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

The purpose and the exactness rationale are front-loaded, then the grammar is enumerated in a compact inline list, then the exclusion is placed last. Every clause carries either a verb, a constraint, or syntax; nothing is redundant with the title or schema.

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

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

For a mutation tool with no output schema and only two parameters, the description covers intent, syntax, timing, and limits adequately. The remaining gap is outcome behavior — no mention of what is returned, whether a failed step aborts the sequence, or which window receives the synthesized events — which matters for a non-idempotent input injector.

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 'gap' and 'steps' are already documented at a basic level; the baseline would be 3. The description earns above that by supplying the step grammar ('move X Y', 'click [X Y]', 'down [X Y]' plus right/middle modifiers, 'wait N') and clarifying that 'wait N' means N additional ticks, which the schema's 'the steps, in order' does not convey. It never explicitly ties the tick unit back to the 'gap' parameter, so it is not quite complete.

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 ('Play a sequence of mouse and keyboard events in one request') plus the timing model ('timed on the Amiga in ticks of 1/50 s'). It also names the sibling tools it competes with ('the separate mouse and key tools'), so an agent can tell it apart from amiga_mouse, amiga_key_press, and amiga_drag without opening those 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 an explicit positive condition ('for gestures that must be exact: a fast drag, a key chord, a burst of typing') and an explicit negative one ('For single actions the separate mouse and key tools are simpler'). That is a clear when-to-use / when-not-to-use routing rule naming the alternatives.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds two facts annotations cannot convey: each entry is both pressed and released (so a modifier chord like ramiga+q is a complete keystroke, not a held state), and input is delivered to the active window, which matters for stateful desktop automation. It stops short of saying what happens if the target window is not focused or whether errors are reported.

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 target, then the accepted key forms, then the alternative-tool pointer in a single compact statement. It is one long semicolon-delimited sentence, which is dense but every clause (vocabulary, modifier syntax, raw code, sibling routing) carries information an agent needs; only the punctuation structure slightly hurts scannability.

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 tool with full schema coverage and no output schema, the description covers everything needed to call it correctly: target window, accepted key formats, press-and-release semantics, and where to go for text entry. The only gap is failure behaviour (no focused window, unsupported key name), which is minor given the tool's simplicity.

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 parameter is a plain string array, so the baseline would be 3. The description nevertheless adds substantial meaning the schema lacks: the enumerated key vocabulary (return, esc, tab, del, backspace, space, f1-f10, arrows, help, kp0-kp9, kpenter), the '+'-joined modifier syntax with named Amiga modifiers (ramiga, lamiga, ctrl, shift, alt), and the raw hex escape hatch (0x45). Since the schema exposes no enum, this list is the only place the accepted values are specified.

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 ("Press keys ... into the active window") and immediately scopes the accepted key vocabulary: named keys, modifier combinations joined with '+', or raw hex codes. It explicitly names the sibling it is not for ("For ordinary text use amiga_key_type"), so an agent can distinguish it from amiga_key_type 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 explicit routing guidance to the alternative tool for ordinary text input, plus a clear statement of the target (the active window). It does not cover other plausible alternatives (e.g. amiga_ui_click for actuating UI controls, amiga_input for bulk input), but the primary ambiguity between typing and pressing is resolved.

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 (not read-only, non-destructive, non-idempotent, closed-world), and the description adds meaningful behavior beyond that: input is delivered via the Amiga keymap to whatever window currently has focus, so focus state determines the outcome. It does not say what happens with untypable characters or repeated invocation effects, which keeps it below a 5.

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

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

Three short sentences, front-loaded with the action and mechanism, then prerequisite, then alternatives. Every clause carries routing or behavioral information; 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 two-parameter, non-destructive input tool with annotations and no output schema, the description covers purpose, prerequisite state, and sibling routing adequately. Minor gaps remain around failure modes (no focused window, unsupported characters) but nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so 'text' and 'enter' are already documented; the description adds only indirect meaning by implying the text must be expressible in the Amiga keymap. It never mentions the 'enter' option or any formatting/length constraints, so it stays at the baseline for a fully covered schema.

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

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

States a specific verb and target ('Type text into the active window') plus the mechanism ('through the Amiga's own keymap, as if typed on its keyboard'), which immediately separates it from raw key events and field-setting siblings.

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

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

Explicitly gives the prerequisite ('Make the right window active first via amiga_ui_click or amiga_mouse') and names two alternatives with their selecting conditions: amiga_key_press for special keys/shortcuts and amiga_ui_set for named text fields. Nothing 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 flag destructiveHint=true, but the description goes well past them by describing the actual mechanics: Ctrl-C is signal-based and "well-behaved programs obey and clean up after," whereas force uses RemTask and leaves memory, files and windows behind and "the system may crash." That consequence detail is exactly the context an agent needs before choosing force, and it also notes the tool reports what was done.

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

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

Three tight sentences ordered by importance: what it does, the safe default, then the dangerous escalation with its consequences. Every clause carries information and the risk warning is not buried.

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 destructive tool with full annotation coverage, the description covers action, targeting, default behavior, escalation condition and collateral damage. The only soft spot is the return value, described only as "what was done" with no output schema to fall back on.

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

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

Schema coverage is 100%, so both parameters are already documented — and the description largely restates them ("by name or by address from amiga_ps," force = RemTask). The only added meaning is the operational rule that force is a last resort after Ctrl-C fails. 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?

"Stop a task or process by name or by address from amiga_ps" gives a specific verb (stop) and resource (task/process) plus the two accepted identifier forms. It clearly separates this from sibling list/introspection tools like amiga_ps and amiga_info without needing the schema.

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

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

The description gives a clear escalation policy: default Ctrl-C, and force only "when Ctrl-C has failed." That is real when-to-use guidance. It does not explicitly compare against siblings such as amiga_break or amiga_health, so the routing is implied rather than stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the description correctly spends its words elsewhere: sort order (drawers first, then by name), the exact output line layout including protection bits and '(dir)' markers, and the fact that it is not recursive. It leaves error behaviour (nonexistent volume, access denied) unstated, which keeps it from a 5.

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

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

Front-loaded with purpose and ordering, then output format, then path semantics, then defaults — a logical progression. It is dense with semicolons and slightly run-on, 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?

With no output schema, the description takes on the burden of describing return shape and does so precisely (one line per entry, type flag, size, protection bits, date/time, name). Combined with the annotations covering safety, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100% and the schema already says empty lists volumes, but the description adds real meaning beyond it: the volume/assign colon syntax ('SYS:', 'Work:Projects', 'RAM:') and the non-obvious rule that '/' is the parent rather than the root. Those are exactly the semantics an agent would otherwise get wrong.

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 files and subdirectories in one Amiga directory') and immediately scopes it as non-recursive and read-only, which cleanly separates it from amiga_read_file, amiga_text, and other content tools in the sibling list.

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

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

Gives a clear operating context: path is optional, and with no path it lists mounted volumes (on Zenix, '/'). It also rules out recursion and clarifies the Amiga path grammar. It does not explicitly name a sibling alternative for reading file contents, so it falls short of a full when-to-use/when-not-to-use 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 already declare the mutating, non-idempotent, non-destructive profile, so the bar is lower. The description adds real context beyond them: it drives the actual system pointer, coordinates follow the amiga_screenshot frame, and omitting x/y acts at the current pointer location. It does not describe the response or any side effects of the click itself (e.g. focus changes), which keeps it below a 5.

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

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

Three compact sentences: capability first, coordinate frame second, sibling routing last. Every clause carries information (modes, defaults, coordinate reference, alternatives) 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?

For a zero-required-parameter pointer tool with no output schema and full schema coverage, the description covers modes, defaults, coordinate frame, and alternatives. The only unaddressed item is what a click returns or what UI state it may change, which is a minor gap given annotations cover the mutation profile.

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 enums are already documented, so the baseline is 3. The description still adds meaning the schema lacks, notably that x and y are optional together (omitting them acts at the pointer) and that the coordinate system matches amiga_screenshot, which disambiguates what 'front screen' coordinates mean.

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

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

The description pairs a specific verb set (move, click, doubleclick, down/up) with a concrete resource (the real mouse pointer on the front screen) and states the no-coordinate behavior. It actively distinguishes itself from sibling tools by naming amiga_ui_click and amiga_drag.

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 routing is given: prefer amiga_ui_click for named gadgets, use this tool for icons and custom-drawn areas, and use amiga_drag for a whole drag. Both an inclusion rule and two exclusions are stated, so an agent can pick between the three pointer tools without opening schemas.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds useful context: the result is in screenshot coordinates, no image is returned, and the location is relative to the front screen. It does not cover error cases or screen-unavailable behavior, but it adds meaningful operational detail beyond the annotations.

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

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

The description is compact and front-loaded: the return value and scope come first, followed by two short clarifications. Every clause earns its place by specifying the output format, absence of an image, and read-only nature.

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

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

For a zero-parameter, read-only tool with annotations covering safety and no output schema, the description supplies the essential return format and coordinate context. An agent has enough information to invoke it correctly without further parameter or return-value documentation.

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

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

There are zero parameters, so there is no parameter meaning for the description to clarify. The baseline for a parameterless tool is a 4, and the description does not introduce any contradictory parameter guidance.

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

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

States a specific verb and resource: 'Return where the mouse pointer is on the front screen,' including the 'x y' coordinate format. It also distinguishes itself from screenshot-like tools with 'No picture is sent' and from mutating tools with 'Read-only,' though it does not name a specific sibling alternative.

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

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

Usage is implied by the read-only, no-image positioning of the tool, but the description gives no explicit when-to-use or when-not-to-use guidance against siblings such as amiga_screenshot or amiga_mouse. The agent can infer the purpose, but routing is left to the agent.

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 safety is covered. The description adds real behavioral detail beyond that: a header line followed by one line per task, the exact column set, and the wildcard semantics of the filter. The trailing 'Read-only' merely repeats the annotation and adds nothing.

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?

It is front-loaded with purpose and output shape, then the filter, then the follow-up tool, in a compact three-sentence block with no filler. The final 'Read-only' clause is the one piece that does not earn its place given the annotations.

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 carries the burden of describing the result format (header plus per-task columns) and the filter semantics. It is nearly complete for a simple read-only listing; only edge behavior such as an empty task list or invalid pattern handling 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%, so the baseline is 3, but the description earns above that by explaining that the pattern keeps only matching names and that '#?' is the Amiga equivalent of '*', with a worked example ('#?shell#?'). That clarifies a syntax convention an agent would otherwise get wrong.

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

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

The description states a specific verb and resource ('List the tasks and processes running on the Amiga') and anchors it with a concrete analogy ('like a Unix ps'), then enumerates the exact output columns. This clearly separates it from siblings such as amiga_windows or amiga_ui_list that also enumerate things.

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 explains what 'pattern' does and explicitly routes the next step: 'The address or name goes to amiga_kill.' That is useful lifecycle guidance. It stops short of naming an exclusion case or the scenario in which a filtered listing is preferable, so it is clear context without explicit when-not-to-use.

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 still adds substantial behavior: Latin-1 decoding, the exact binary-detection heuristic (zero byte in first 4 KB), and the literal return prefix 'binary file, N bytes, base64:'. That is the kind of output-shape detail an agent cannot infer from structured fields.

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

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

Three short sentences: purpose first, then output format, then failure mode and alternative. Every sentence carries distinct information with no repetition of the title or annotations.

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 takes on the burden of describing return values and does so precisely, including the binary case. For a one-parameter read tool, 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 coverage is 100% and the path parameter already carries an example, so the description only reinforces that it is a 'full Amiga path'. Baseline 3 applies since the schema does the heavy lifting for the single parameter.

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

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

States a specific verb and resource ('Copy one file from the Amiga and return its contents'), immediately distinguishing it from write/list siblings. The parenthetical contrast with amiga_ls for directories further sharpens its identity.

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 failure conditions and routes the directory case to amiga_ls, which is a real alternative pointer. It does not cover other plausible alternatives (e.g. amiga_text or amiga_write_file) or note when a bulk read is preferable, so it stops short of full when/when-not guidance.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds real value beyond them: the checksum comparison model, the three possible answer states, and the cost motivation for polling. It does not say what happens with an invalid or stale checksum, or how a region outside the screen bounds is treated, 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?

Front-loaded with the core purpose, then the protocol, then the alternative — a good ordering. The prose is dense and reads as a semicolon-chained run-on, but no sentence is 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 carries the burden of return values and does so by naming the three answer states. For a three-parameter polling tool with full annotation coverage, this is nearly complete; only error/stale-checksum behavior is 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% and the nested region object is self-describing, so baseline is 3; the description earns an extra point by explaining the temporal coupling between 'since' and a prior call's checksum, which the schema alone cannot convey. It adds no detail on how 'window' matches titles beyond the schema's 'part of its title'.

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 plus resource ('tell whether the screen, a window or a rectangle has changed') and immediately differentiates itself from amiga_screenshot by noting no picture is sent. The checksum mechanism makes the tool's identity unambiguous against siblings like amiga_wait.

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 the exact call protocol: first call without 'since' returns 'first look' plus a checksum, later calls pass that checksum as 'since'. It also names the alternative for the blocking case ('to block until a change use amiga_wait with what=change') and the condition choosing it ('cheap polling when a screenshot would be too big').

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 readOnlyHint=false, and the description earns its keep by explaining why: ARexx can reach any program's port and run AmigaDOS commands, so it can change anything. It also discloses the blocking/long-running nature and the return shape ('what it SAYs, then [rc N]') despite no output schema. It stops short of describing failure modes or partial output on timeout, so not a 5.

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

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

Three short sentences, each carrying distinct information: what it does, what it returns, how dangerous it is, and which sibling to use instead. Zero padding and the core action is front-loaded.

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

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

The tool is simple (2 params, no nested objects, no output schema), and the description covers the return value, the blocking semantics, the prerequisite, and the risk profile. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so both 'program' and 'max_time' are already documented in the schema, including the default wait. The description only restates that the program is supplied as text and otherwise adds no syntax or format detail; 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 opens with a specific verb+resource ('Run an ARexx program given as text') plus the blocking behavior ('wait for it to end'), and explicitly contrasts itself with the sibling amiga_arexx, so an agent can separate the two 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?

It gives an explicit alternative and the condition that selects it ('To send one command to one program's port use amiga_arexx'), and it names the prerequisite ('Needs RexxMast running'). That is exactly the routing information an agent needs before invoking.

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 non-idempotent, and the description reinforces this with 'The command can do anything a Shell can, including delete files.' It also discloses the blocking behavior, the merged stdout/stderr return shape, the '[return code N]' trailer with the meaning of each code, and that max_time triggers a Ctrl-C – context the annotations cannot express.

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 action and return contract, then progressively narrower routing advice. Every sentence carries a distinct fact (return format, code meanings, danger, backgrounding idiom, stuck-command escape hatches, alternatives) 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?

With no output schema, the description fully carries the return contract: merged stdout/stderr followed by a '[return code N]' line with a decoding table. Combined with the timeout semantics and the windowed-program idiom, an agent has everything needed to call and interpret this correctly.

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

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

Schema coverage is 100%, and the schema already documents both parameters including the Ctrl-C/default-600s behavior of max_time. The description adds only the framing that the command is 'as typed in a Shell' and the example-style usage, so the schema is doing the heavy lifting – 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 ('Run one AmigaDOS command line ... and wait for it to finish') and immediately delimits itself against siblings: 'Prefer amiga_ls and amiga_read_file for looking at files' and 'use amiga_wait for its window'. An agent can place this tool relative to the file, window, and process siblings 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 explicit when-to-use alternatives with the condition that selects them: use amiga_ls/amiga_read_file for inspecting files, use 'Run >NIL: Program' plus amiga_wait for windowed programs, and amiga_slots/amiga_break for stuck commands. Both routing and exclusion guidance are present.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavior beyond the annotations: the return ordering is front-first, the listed fields are included, and the scope is limited to screens. It repeats "Read-only" but still adds substantive context, though it does not discuss anything like pagination or failure behavior.

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

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

It is two compact sentences with no wasted wording. The scope and ordering are front-loaded, followed by the sibling alternative, which is exactly the information an agent needs first.

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

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

With no parameters, no output schema, and annotations covering the safety profile, the description supplies the remaining essentials: returned fields, ordering, and screen-vs-window scope. Nothing material is missing for correct invocation.

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

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

There are zero parameters, so the baseline is 4. The description adds no parameter semantics because none are needed, and the empty schema is fully consistent with taking no arguments.

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

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

The description states a specific verb and resource ("List the open Intuition screens") and names the distinguishing scope: screens only, front first, with the listed fields. It explicitly separates this from amiga_windows, so an agent can identify the right tool without opening another 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 gives explicit when-to-use guidance ("Only screens") and names the alternative for the adjacent case ("for the windows on them use amiga_windows"). That is a clear routing rule between siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, and the description reinforces this with 'Read-only.' Beyond that it discloses the return shape (a line with the size) and a key behavioral fact: pixel coordinates in the image map exactly to the ones amiga_mouse, amiga_drag and amiga_input consume. It does not describe the image encoding/attachment mechanics or clipping behavior for off-screen windows, which keeps it below a 5.

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

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

Front-loaded with the core action, then scoping options, then the coordinate-frame contract, then routing to alternatives. No filler sentences; every clause carries information an agent needs.

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 return-value information, and it does partially by mentioning the accompanying size line; the PNG payload itself is implied. For a 2-optional-parameter read tool with full annotation coverage this is nearly complete, missing only edge-case behavior (e.g., what happens if a window title matches multiple windows).

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 both parameters are described there (region as a nested object with x/y/width/height, window as a partial title match), so baseline is 3. The description earns above baseline by establishing that region coordinates share the coordinate system of the pointer/input tools and that window/region capture is cheaper than full-screen.

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 ('Capture the front screen as a PNG image') plus its three scoping variants (full screen, one window, a rectangle). It is immediately distinguishable from amiga_windows, amiga_ui_list and amiga_region_changed, which it names.

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 guidance ('see the screen before clicking') plus two named alternatives with the conditions that select them: amiga_ui_list for finding buttons by name (cheaper) and amiga_region_changed for change detection only. Includes the tradeoff rationale (window/region is smaller and faster).

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 read-only/idempotent, and the description still adds substantive behavior beyond them: the fixed pool of four run slots, the per-line return fields (slot number, state, elapsed seconds, command), and the exact sentinel output 'all run slots are free' when nothing runs. With no output schema, this return-shape disclosure is especially valuable.

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 what it returns, then the trigger, then the follow-up tool, then the alternative, then a one-word safety note. Every clause carries distinct information and 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?

For a zero-parameter read-only inspection tool with no output schema, the description covers purpose, exact return format, sentinel case, trigger condition, and sibling routing. An agent knows exactly when and how to call it and what it will see.

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

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

The tool takes no parameters, so the baseline is 4; the description correctly implies no inputs are needed and spends its words on output and routing instead. Nothing about parameters needs clarifying.

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 amiga_run commands that are running now', and immediately scopes it to daemon run slots, which separates it from amiga_ps (all tasks) 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 trigger ('when amiga_run timed out or seems stuck'), an explicit follow-up ('then amiga_break'), and an explicit alternative ('For all tasks on the machine use amiga_ps'), covering both when to use it and when to use something else.

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, non-destructive and openWorldHint=false, so the safety profile is covered; the trailing 'Read-only.' is redundant with them. What the description genuinely adds is the platform constraint and the failure behavior on AmigaOS, which is not encoded anywhere in the annotations. It stops short of describing return shape details such as line count or handling of an empty console.

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

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

Two short sentences, front-loaded with the platform scope and the core capability, then the fallback. No filler; the parenthetical '(not AmigaOS)' and the fallback clause both earn their place as routing 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 single-optional-parameter read tool with full schema coverage and complete safety annotations, the description covers purpose, platform gating, fallback, and output format (lines of text). Only minor edge cases (empty console, whether non-visible consoles can be read) are left unstated.

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

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

There is one optional parameter and the schema already documents it fully ('console 1-10 (default: the one shown)'), giving 100% coverage. The description adds no further meaning about the console argument, 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 ('return the text on a Zenix console as lines') plus the reason ('so the screen can be read without a picture'), which immediately separates it from the screenshot siblings. An agent knows exactly what it gets back: text lines rather than an image.

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

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

Gives an explicit platform precondition ('Zenix only (not AmigaOS)'), states the failure mode ('On AmigaOS it fails'), and names the correct alternative ('use amiga_screenshot'). This is a complete when/when-not/alternative routing rule, which is exactly what the sibling list of 29 tools demands.

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 non-readOnly, non-idempotent, non-destructive, but the description adds the traits that matter: the window is brought to the front as a side effect, the click is a real mouse event, and the program may then do anything the gadget does (Quit, Delete). That last warning meaningfully tempers the destructiveHint=false signal without contradicting it, and the failure case is disclosed.

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 and its prerequisite are front-loaded, then disambiguation, then return/failure behavior, then the risk note. No sentence is filler and the ordering matches how an agent would need the information.

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

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

With no output schema, the description still states what is returned (which gadget, in which window) and the failure mode. For a 6-optional-parameter interaction tool with full schema coverage and annotations, nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine selection semantics by explaining how id, nth, kind and window combine to disambiguate multiple matches and by explaining what the special border-gadget names mean. It stays silent on the effect of 'double', which the schema already labels.

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 a gadget found by its label') and anchors it to the sibling that enumerates those labels (amiga_ui_list), which separates it from amiga_pointer, amiga_mouse and amiga_ui_set. The note that 'close', 'depth', 'zoom' and 'size' name border gadgets extends the concept precisely.

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 clear operating context: labels come from amiga_ui_list, window is raised first, and ambiguity is resolved with window, kind, nth, or the gadget id. It does not explicitly say when to prefer raw amiga_pointer/amiga_mouse instead, so the alternative routing 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 readOnly, idempotent and non-destructive, so safety is covered; the description adds real value beyond that by disclosing coverage boundaries (Intuition, GadTools, ReAction, MUI 4/5 supported; custom-drawn UIs invisible) and the shape of each output line including flags like [disabled] or [selected]. The trailing 'Read-only' is a minor restatement of the annotation, but the toolkit-support caveat is genuinely useful behavioral context.

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 scope comes first, then the output format, then supported toolkits and the limitation, then the workflow rule. Despite being dense, every sentence carries distinct information and none is redundant 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 available, the description takes on the burden of describing return values and does so concretely — one line per gadget with kind, label, id, position, size, value and state flags, and menu items as 'Menu/Item' paths with shortcuts. Combined with the usage rule and the coverage limitation, an agent has everything needed to call it and interpret results.

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 optional parameters (window title substring filter, all_screens) are already documented in the schema. The description only implicitly corroborates the default by saying 'windows on the front screen'; it adds no syntax or matching guidance beyond that, 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 (list) and a precisely scoped resource: gadgets (buttons, text fields, checkboxes, cycle gadgets, sliders, lists and rows) plus menu items of windows on the front screen. It also distinguishes itself from amiga_screenshot for custom-drawn content and from the amiga_windows sibling by focusing on widget-level inventory.

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 rule: call it before amiga_ui_click, amiga_ui_set and amiga_ui_menu to learn exact names. It also names the exclusion case — custom-drawn content in games or paint programs — and routes the agent to amiga_screenshot instead.

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=false, destructiveHint=false, idempotentHint=false). The description adds real context beyond them: the menu is operated invisibly, and 'The program then does whatever that item does' warns that consequences depend entirely on the chosen item, which usefully reinforces the non-idempotent, side-effecting nature. It stops short of saying what happens when a path is ambiguous or the item is disabled or missing.

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, each with a distinct job: what to pass, the mouse-free behavior plus consequence, and the discovery alternative. Front-loaded with the action and example format, 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 two-parameter, no-output-schema UI action with annotations present, the description covers syntax, scope, default window, invisibility, and the pointer to the listing tool. It lacks only edge-case behavior (unmatched path, duplicate names, disabled items) and any assertion about what is returned on success.

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 genuine meaning: 'path' may be a full path or a bare leaf name when unique, which the schema's 'menu path' text does not convey; and 'window' defaults to the active window, matching the schema while clarifying default behavior. Ambiguity handling for duplicate names is still unspecified.

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 ('Choose a menu item by name'), gives concrete path syntax ('Project/Save As', bare 'Quit'), and scopes the target ('in the active window (or the one named)'). This clearly separates it from sibling pointer/click tools like amiga_ui_click or amiga_mouse.

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 explains when the tool applies (menu-driven actions, no mouse movement or visible menu needed) and routes discovery to the sibling 'amiga_ui_list shows the menu paths'. It does not state explicit exclusions, e.g., when to prefer amiga_ui_click instead, but the intended use case 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 declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, but the description adds what those hints cannot: the field is cleared before typing, keystrokes are translated through the Amiga keymap, and Return is pressed unless no_enter is set. It also discloses the return value (which field was set). Remaining gaps are minor: no statement of what happens when the label matches nothing or when several fields match.

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

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

Three tight sentences with no filler, front-loading what the tool does before the prerequisite and the alternative. Slightly dense clause chaining in the first sentence, but every phrase carries actionable 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 7-parameter mutation tool with no output schema and 100% schema coverage, the description covers the action sequence, the prerequisite lookup tool, the sibling alternative, the Return-press flag, and the return value. It does not describe failure or ambiguity handling (no match, multiple matches handled via nth), which is the remaining shortfall.

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

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

Schema description coverage is 100%, so all seven parameters already carry their own documentation. The description reinforces the identifiers (label/id used to locate the field) and the no_enter effect ('press Return unless no_enter is set'), but adds little syntax or semantics beyond the schema. Baseline 3 applies where 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 plus full mechanics: 'Fill a text (string) gadget found by its label: click it, clear it, type the text through the Amiga's keymap, and press Return unless no_enter is set.' It also names the sibling it is not (amiga_key_type for Shell/editor), so an agent can distinguish it 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 prerequisite ("Find the field's label or id with amiga_ui_list first") and an explicit alternative with the condition that selects it ("For typing into a Shell or editor use amiga_key_type"). Both when-to-use and when-to-use-something-else are covered.

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=false, and the description is consistent with them ('Read-only'). It adds real behavioral context the annotations do not: the call blocks server-side so no network traffic occurs while waiting, it returns one line describing the event, and it fails with an error on timeout. Return-shape and failure details are exactly what an agent needs for a blocking call.

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

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

The block-on conditions are front-loaded and the operational notes (server-side watching, return value, timeout failure) follow in a logical order. Every sentence carries information, though the long opening sentence packs several modes together and could read more cleanly as a list.

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 five-parameter, nested-object, blocking tool with no output schema, the description covers the essential gaps: what it waits for, that it blocks on the server, what it returns, and how it fails. Only the relationship to overlapping sibling wait tools is left unexplained.

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 five parameters are already documented. The description restates the mode semantics in prose (including gone=true and 'screen settles (stops changing)') but adds no new distinctions, such as how region interacts with name or default behavior when name is omitted for change/still. Baseline 3 applies.

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

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

The description states a specific verb and resource ('Block until something happens on the Amiga') and enumerates the trigger classes: window/task appearance or disappearance, file appearance, screen change, screen settling. It is clear what the tool does, but it never distinguishes itself from siblings like amiga_wait_text or amiga_region_changed, which cover overlapping waiting use cases.

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 starting a program or clicking something that takes time' gives a concrete usage context. It also implicitly contrasts with sleeping, which is a useful framing. However, it offers no when-not guidance and no pointer to the text- or region-specific wait alternatives.

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

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

Annotations already cover the safe/read-only profile, and the description adds real behavior beyond them: the match is performed on the Amiga side so nothing crosses the network meanwhile, and it fails after 'timeout' seconds rather than hanging. It does not say what a successful answer contains, which is the only meaningful 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 tight sentences, front-loaded with the platform restriction that matters most, then the match semantics, then the failure mode. No filler, though the phrasing 'The Amiga watches, so nothing crosses the network meanwhile' is slightly awkward.

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 should say what comes back on a match (the matched line, a capture, an empty success). 'Answers when a line matches' is too vague for a tool whose entire purpose is returning a match 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 console numbering, pattern and timeout are already documented with defaults. The description adds one genuine clarification — that the pattern is an extended regular expression — which is useful but does not go beyond that single parameter.

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

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

States a specific verb and resource ('wait until a line of the console matches a pattern') and pins the scope to Zenix only, not AmigaOS. The regex hint and 'login:' example make it immediately distinguishable from a generic wait like amiga_wait.

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 clear context for use (waiting for a console prompt on Zenix) and an explicit platform exclusion. It stops short of naming an alternative sibling such as amiga_wait or amiga_text and when those would be preferred instead, so routing between wait-style tools 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 cover read-only/idempotent/non-destructive, and the description reinforces this without contradicting it. It adds real behavioral value in the ordering guarantee ('front first') and the fact that flags such as [active] and [backdrop] are attached to each entry, which the annotations cannot convey.

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 compact sentences, front-loaded with the action and result ordering, followed by the routing hint and a one-word safety note. Every sentence earns its place; the trailing 'Read-only' is the only mild redundancy with annotations.

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 parameters, no output schema, and simple read-only semantics, the description supplies everything needed: what is listed, ordering, entry contents, and downstream usage. An agent can invoke and chain it correctly without further context.

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, so the schema baseline is already 4 and the description correctly adds no param noise. It instead clarifies where the value for a related 'window' argument originates, which helps the agent chain this tool with others.

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 every screen and the windows on it') and enumerates exactly what is returned: title, position, size, owning task, and status flags. It also differentiates itself from the sibling amiga_ui_list by scoping that tool to buttons inside windows.

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 case — finding a window's title to feed the 'window' argument of other tools — and names the alternative tool (amiga_ui_list) with the condition that selects it. Nothing 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?

Beyond the annotations (which only say destructive/openWorld=false/idempotent=false), the description discloses exactly what gets destroyed ('An existing file of that name is replaced'), what will fail ('parent directory must exist'), a safety guardrail blocking SYS:, C:, S:, LIBS:, DEVS:, L: locations, and the encoding transformation applied to text. That is precisely the extra context an agent needs for a destructive write.

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

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

Six short sentences, front-loaded with the action and replace behavior, then encoding choice, preconditions, safety refusal, and return value. No filler or restated title, and each sentence carries a distinct constraint.

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

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

With no output schema, the description covers the return value ('a line with the bytes written'), and it supplies the safety, precondition, and encoding facts a destructive 3-parameter tool needs. Nothing material for correct invocation is missing.

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

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

Schema coverage is 100%, so baseline is 3, and the description earns more by adding semantics the schema lacks: Latin-1 encoding plus LF normalization for 'text', binary intent for 'base64', and the mutual exclusion rule (no oneOf in the schema enforces it). It adds nothing about path formatting or validation beyond the schema's example and the system-place refusal.

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

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

The opening sentence gives a specific verb and resource with scope ('Create or replace one file on the Amiga'), which is immediately distinguishable from amiga_read_file, amiga_ls, and amiga_text. Replace semantics are stated up front, so the agent knows this is a write, not a read.

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 clearly states when each content mode applies ('text' for Latin-1 text with LF line ends, 'base64' for binary) and explicitly forbids supplying both, plus preconditions (parent directory must exist). It does not name or defer to any sibling tool, but no sibling in the list offers file writing, so there is no real routing ambiguity to resolve.

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