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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that this performs an action/click and that the reply reports what was done rather than what the click caused, which is meaningful side-effect context. However, it omits permissions, reversibility, what `double` changes, and what practical effects may follow, leaving significant gaps for a UI mutation tool.

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

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

The description is front-loaded with the key distinction and every sentence contributes to that distinction or to the read-back caveat. The prose is somewhat indirect, using an analogy and backticked sibling reference, but it remains appropriately sized. It is clear and structured without excessive repetition.

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

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

The tool has four parameters with 0% schema description coverage and no annotations, so description-side guidance is important. The description explains the action semantics and read-back limitation, but it does not explain how to identify the required row or control/dialog parameters, nor what `double` toggles. Given an output schema exists, the return-value caveat is sufficient, but invocation guidance remains incomplete.

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

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

Schema description coverage is 0% and none of the four parameters are meaningfully explained. The description references a row conceptually and invokes a click-like action, but it does not define the required `control_label`, `dialog_title`, `row` format, or what `double` does. It therefore provides almost no parameter semantics to compensate for the empty schema descriptions.

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

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

The first sentence states a specific action and resource: invoking a row rather than selecting it. It also names the contrasting sibling `app_set_dialog_control(select_row=...)`, so an agent can distinguish the two without opening either schema. The scope is slightly less precise than a 5 because it does not explicitly say which kind of row/panel context this applies to.

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 when-to-use contrast: use this tool to ACT on a row, whereas `app_set_dialog_control(select_row=...)` only highlights it. The document-opening analogy makes the intended outcome concrete. It stops short of 5 because it does not mention other potentially relevant UI-action siblings or any when-not-to-use conditions beyond the selection case.

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

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

With no annotations, the description carries the full burden. It discloses the key prerequisite (StartMCPServer script running), what the tool verifies (Altium running and script responding), and that it returns a dictionary with attachment status. It does not mention side effects or idempotency, but for a connection tool this is largely sufficient.

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 three sentences, front-loaded with the core action, followed by essential verification details and prerequisite. Every sentence contributes meaning without waste.

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

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

Given the tool's simplicity (no parameters) and the presence of an output schema, the description covers all necessary aspects: purpose, prerequisite, verification behavior, and return type. Nothing critical 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?

The tool has zero parameters, so there is no parameter semantics to convey. The baseline score for zero parameters is 4.

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 clearly states a specific verb and resource: 'Connect to a running Altium Designer instance.' It also explains the verification aspect. However, it does not distinguish this tool from similar siblings like app_ping or app_get_status, which also check Altium's responsiveness.

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

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

The description provides clear context for when to use the tool: to connect and verify that Altium is running and the polling script is responding. It mentions the prerequisite that the Altium_API.PrjScr script must be running. However, it does not explicitly state when not to use it or name 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?

No annotations are provided, yet the description carries the full behavioral burden: it distinguishes click vs drag, explains the stepwise drag motion (jump reads as click at destination), discloses there is no read-back at all, and prescribes a bridge read to confirm effects. This is unusually rich disclosure for a gesture 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?

Front-loaded with the core action, then behavior, then the read-back caveat—well ordered. Slightly wordy in the 'no named controls / there was no way to make one' passage, which restates the same point twice, but nearly every sentence contributes.

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?

An output schema exists, yet the description adds the crucial caveat that the reply reports only the gesture, not its effect, which an agent would otherwise miss. Drag semantics and the verification path are covered; only the `double` gesture is left unexplained, which keeps it just short of complete.

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

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

Schema coverage is 0% and titles are bare, so the description must carry meaning. It clarifies x/y as screen coordinates and to_x/to_y as a drag target with stepwise motion, but leaves the `double` boolean completely undocumented in both schema and description—a meaningful gap since double-click is a distinct gesture.

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 set (click/drag) on a specific resource (editor canvas) at screen coordinates, and explicitly contrasts itself with siblings: the canvas has no named controls, so 'every other tool here could not touch it.' An agent can tell this apart from app_invoke_element/obj_select without reading 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?

Clearly explains when to reach for this tool (canvas has no named controls, so pointer gestures are the only route) and points to a 'bridge read' for verification instead of this tool. It doesn't explicitly say to prefer app_invoke_element when a named control exists, so the exclusion 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?

With no annotations, the description carries the full burden and does: it discloses content-addressed dedup and cheap repeat checkpoints, notes that a checkpoint is taken even if the flush fails, and warns that a post-failure checkpoint holds only on-disk state — precisely the failure mode that matters. That is behavior an agent could not infer from name or schema.

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

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

The key guidance is front-loaded in the first paragraph, and the Args/Returns blocks are dense rather than padded. Slight over-explanation in the save_error/note walkthrough keeps it from a 5, but nothing is wasted for a mutating tool with no 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?

Covers what is snapshotted, the storage model, the risk-mitigation use case, both parameters, and the failure return shape. An output schema exists, yet the extra note about the `saved`/`save_error` fields adds decision-relevant nuance rather than merely restating it.

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

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

Schema description coverage is 0%, so the description must compensate and does: it explains `label` with an example, and explains `save_first` including its default True and the reason for it (flush dirty Altium docs so in-editor changes are captured). Meaning is added well beyond the bare type/default in the schema.

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

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

Opens with a specific verb and resource ('Snapshot the focused project') plus the purpose (session revertibility), and names the counterpart tool app_restore_checkpoint. A reader can immediately tell this apart from save tools like app_save_all or proj_save.

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 states when to take one ('before any risky autonomous edit') and how it relates to the alternative ('restore with `app_restore_checkpoint`'). It also frames it as the undo the live bridge lacks, which disambiguates it from the design/review snapshot tools.

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

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

No annotations exist, so the description carries the whole burden and does so well: it discloses focus stealing, pointer movement and restoration, the may_steal_focus gate, retry-on-empty-level behavior, what counts as failure (a menu left open means no command ran), and the offered/first_read diagnostics. It stops short only of explicit safety or reversibility framing for arbitrary menu commands, which is a minor gap rather than a missing one.

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 organized under scannable headings (PATH BY NAME, IT NEEDS THE FOREGROUND, THE MENU BAR IS PER EDITOR). Some passages, such as the internal task-number rationale and the DevExpress bar explanation, are longer than strictly needed, though they do justify the tool's existence.

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

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

For a complex, focus-stealing, arbitrary-command tool with a four-parameter schema that lacks field descriptions, everything an agent needs is present: path syntax, gating, context dependence, expected dialog verification, failure semantics, and diagnostics. The Returns section slightly duplicates the output schema but usefully explains what 'ok', 'offered', and 'retried' actually mean.

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

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

Schema description coverage is 0%, so the description must compensate and does: menu_path syntax is given with concrete examples, rules for accelerator markers and trailing ellipses, multi-level submenu handling, and the rationale for names over positions; may_steal_focus, list_only, and expect_dialog each get behavioral meaning beyond their bare boolean/string types, including how expect_dialog changes what 'ok' means.

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

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

Opens with a specific verb+resource+mechanism: 'Invoke ANY Altium menu command by path, by driving the menu.' It immediately distinguishes itself from the closest sibling: 'Use this when app_run_menu will not do,' and explains the sibling's failure mode (reports success for commands it never invokes). An agent can pick between 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?

Explicit when-to-use (app_run_menu is unreliable), when-not-by-default (gated behind may_steal_focus), prerequisites (focus the matching document first because the menu bar is per editor), and handoff (dialogs are read with app_list_open_dialogs). It also names the discovery path: list_only reports what the current editor context offers.

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

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

With no annotations, the description carries the full burden and does so: it discloses the refusal condition, the destructive side effect of discard_changes (flag cleared, edits LOST, no save prompt), the post-condition check ("says whether it is really gone"), and the error cases. The caveat that the modified read can miss in-editor edits and that a save prompt may still appear is exactly the kind of non-obvious behavior an agent needs.

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 key distinction and the destructive warning, and the Args/Returns blocks are readable. The Returns block partially duplicates the existing output schema, though it adds the error conditions, so the slight redundancy is defensible rather than wasteful.

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, focus-independent document close with a 0%-documented schema and no annotations, the description covers scope, refusal semantics, data-loss risk, error conditions and post-condition reporting. Even though an output schema exists, the description's mention of the error cases adds the missing piece an agent needs.

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 0%, so the description must compensate and does: file_path is specified as the full path in the exact form app_list_documents reports it, and discard_changes is given meaning far beyond a boolean default (clears the modified flag first, suppresses the save prompt, loses edits, when it 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 ("Close ONE open document") plus the lookup key ("found by its full path") and the focus-independence ("whatever has focus"). It then explicitly separates itself from the workspace-manager close that acts on the FOCUSED object, so an agent can pick between them 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 alternative path (closing via the workspace manager) and the condition that distinguishes it, then gives an explicit when-to-use / when-not-to-use rule for discard_changes: "For scratch copies and documents Altium changed by merely opening them, never for work." Preconditions (refuses a document that reads modified) are stated up front.

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

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

With no annotations present, the description carries the full burden and does so: it discloses the failure modes it exists to catch (pcb_ tools silently resolving a different open document, DelphiScript unit caching masking a deployed fix, in-memory edits absent from disk), states the call is cheap and derived from existing reads so it cannot disagree with the tools it summarises, and defines the empty-warnings and next_step semantics.

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 imperative and the one-line purpose, then a scannable bulleted list of the four facts, followed by the exclusion and return shape. Slightly verbose in places ("Each has cost a session on its own, and each was individually available and individually unasked for"), but nearly every sentence 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?

Although an output schema exists and would excuse omitting return values, the description still sketches the response fields and explains how to read warnings and next_step. Combined with the explicit non-coverage caveat, an agent has everything needed to decide to call it and to interpret the result.

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

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

The tool takes zero parameters, so there is no parameter semantics to document — the baseline for a no-arg tool applies. The description correctly spends no words on inputs and instead invests in output interpretation.

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 — a single-call situational read — and enumerates exactly the four facts it returns (focused document and kind, script/disk version match, unsaved edits, bridge health). It also explicitly bounds scope against nearby capabilities ("composes existing reads rather than adding a bridge call"), so an agent can tell it apart from app_get_status or app_get_active_document.

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?

"Run this before anything else" is an unambiguous when-to-use directive, and the closing section names an explicit exclusion with a concrete alternative: library component state is not covered, so use lib_set_current_component instead of assuming. Both the positive and negative routing conditions are spelled out.

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

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

With no annotations, the description carries the full burden and does so well: without item it opens, reads, and closes the menu without invoking anything; leaving a popup open blocks the next operation and looks like a hang. It also discloses the failure return shape with offered entries.

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 front-loaded and well structured with Args and Returns sections. Some rhetorical phrasing such as 'ENTIRELY UNREACHABLE' and 'leaves most of the editor shut' is less concise, though it reinforces why the tool matters.

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 three-parameter UI automation tool with no annotations, the description covers purpose, usage rationale, parameter sources, empty-item behavior, blocking side effects, and both success and failure return shapes. An output schema exists, so return values are additionally supported structurally.

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 0%, so the description must compensate, and it does: x and y are screen coordinates with sources from app_list_panels and app_set_dialog_control(list_only=true), while item is a '|' path matched by name at each nesting level. It also explains the special empty-item behavior.

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

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

The first sentence gives a specific verb and resource: right-click at a point to read or choose from a context menu. The description also distinguishes this from top-level menu bar tools by explaining that context menus contain actions no top-level menu duplicates.

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

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

It clearly explains when this tool is necessary: context menu actions for components, nets, polygons, and panel rows that the menu bar does not expose. It does not explicitly name the sibling menu-bar tools as alternatives, but the conceptual alternative is clear.

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

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

With no annotations, the description carries the full burden and does well: it discloses that the new document is focused on return, why the `focused` flag matters for subsequent library/board calls, and that a failed save is raised as an error naming the missing folder rather than a silent `saved: false`. It does not address what happens if a file already exists at `file_path` or permission/overwrite behavior, which is the remaining gap for a disk-writing mutation.

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

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

Purpose sentence is front-loaded and the Args block is justified by the 0% schema coverage. The paragraph on focus/error semantics is slightly repetitive ('a new one left behind the old meant the next call wrote into the old one'), but each sentence informs a real calling decision.

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 4-param creation tool with no annotations, the description covers purpose, all parameters, focus side effects, project attachment, and error semantics, and even restates the return keys despite an output schema existing. An agent has everything needed to call it correctly.

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

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

Schema coverage is 0%, so the description must compensate and does: it enumerates valid `kind` values, requires absolute paths with Windows backslashes for `file_path`, explains `name` defaults to the filename, and explains the `add_to_project` default and what False means. Every parameter gains meaning beyond the bare schema titles.

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

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

Opens with a specific verb+resource+effect: 'Create a new blank document of a given kind and save it to disk,' and names the underlying operation. It distinguishes itself from near-siblings like app_save_document, app_close_document, and the lib_create_* tools by emphasizing a new blank document written to an explicit path.

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

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

Explicitly says when to reach for it ('Use this to create a .PcbDoc before running update_pcb, to spin up a fresh .SchDoc, library, OutJob'), giving concrete precursor contexts. It does not contrast with proj_add_document (which attaches an existing file to a project), so the alternative routing is left implicit 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?

No annotations exist, so the description carries the full load — and it does: it discloses an implicit side effect (flushes every dirty document via save_all before stopping), the ~500 ms shutdown latency, the fact that Altium's script-backed UI commands are blocked while attached, and the non-recoverable-without-user-action consequence of detaching. That is exactly the context an agent needs before an irreversible session-ending 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?

Front-loaded with the imperative and the 'when finished' trigger, followed by justification and then the warning. It runs a bit long across several short paragraphs, but nearly every sentence carries a distinct, decision-relevant fact (keep-alive cadence, UI blocking, save_all, restart requirement).

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

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

Covers trigger, side effects (auto-save via save_all), mechanism, latency, post-state of Altium, and the recovery path. An output schema exists so the description need only note the return ('dictionary confirming detachment'), which it does. Nothing an agent needs to call this safely 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?

Zero parameters, so no parameter semantics are needed; per the rubric a no-parameter tool baselines at 4. The description correctly refrains from inventing parameters, though it could note the absence of options (no force/keep-session flag).

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

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

States a specific verb and resource: stops the Altium MCP polling loop / keep-alive server, and is clearly distinguishable from siblings like app_attach, app_ping and app_save_all. It also names the mechanism (sends application.stop_server so the DelphiScript loop exits) so the agent knows exactly what is being terminated.

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 imperative ('CALL THIS WHEN YOU'RE FINISHED'), an explicit timing condition ('once you've finished your Altium work for the session'), and an explicit exclusion ('Don't detach until you're confident you're done', since re-attaching requires the user to relaunch StartMCPServer manually). The alternative path (keep the session attached, or use app_save_all at intermediate checkpoints) is implied by the described consequences.

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

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

With no annotations, the description carries the burden and does reasonably well: the read-only nature is implicit in 'enumerate'/'Reports', and the truncation to the first 10 matches is explicitly disclosed. It omits the requirement that Altium be attached/active and doesn't state permissions, but the behavior disclosed is accurate and useful.

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

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

Four short sentences, front-loaded with the purpose and followed by the reported fields. The trailing sentence about the dispatcher is slightly internal but still justifies the tool's existence.

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?

An output schema exists, so restating return fields is not strictly needed, though it is harmless. The real gap is the sole input: pattern semantics are left entirely undocumented, which is the one thing an agent must get right to call this tool.

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

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

There is one parameter ('pattern', default request_*.json) with 0% schema description coverage. The description only refers to 'the pattern used' in the output list; it never explains the matching syntax (glob wildcards, case sensitivity, whether it is a filename or path pattern), so an agent must guess how to construct it.

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

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

States a specific verb and resource (enumerate workspace files) plus the underlying mechanism (Altium's FindFiles helper). It doesn't name any sibling or contrast itself with a general listing tool, but the 'Diagnostic:' prefix carves out a clear niche among the ~200 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?

'Used to validate the per-request file enumeration that the dispatcher relies on' gives a concrete context for when this tool is appropriate, which is more than most siblings offer. It stops short of naming when NOT to use it or what alternative listing tool to reach for 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?

No annotations, so the description carries full burden, and it does disclose the key non-obvious behavioral trait: that controls on non-selected tab pages are invisible to app_set_dialog_control and were previously misreported as absent. It also states that listing reports which page is selected. It does not say whether switching persists, requires an open dialog, or errors on unknown names.

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

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

Front-loaded with the verb+resource, then a short rationale and the no-name rule; every sentence earns its place. The all-caps historical aside ('Nothing could switch one...') is slightly long-winded but it teaches a genuine gotcha, so it is defensible rather than wasted.

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

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

An output schema exists, so return-value explanation is correctly omitted. But for a 2-parameter tool with zero schema coverage and no annotations, the description leaves the dialog-targeting parameter and error behavior unexplained, which is not enough for an agent to call it confidently.

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

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

Schema description coverage is 0%, so the description must compensate. It only implies that ``name`` is a tab page name and that omitting it triggers listing mode; ``dialog_title`` is never mentioned at all, leaving the agent unable to know how the target dialog is chosen or whether it defaults to the active dialog.

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?

First sentence states two concrete operations on a concrete resource: list a dialog's tab pages, or switch to one. The rationale paragraph explicitly distinguishes it from sibling app_set_dialog_control, so an agent can see why this tool exists. Not a 5 only because the dual mode (list vs. switch) is signalled purely by presence/absence of a parameter rather than stated as two distinct behaviors.

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 when-to-use context: property dialogs hide controls behind tabs, and app_set_dialog_control only sees the front page, so you must switch tabs before reading controls there. The no-``name`` case is explicitly designated as the listing mode. Missing any statement about prerequisites (is a dialog required to be open?) or what happens when the named tab does not exist.

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

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

With no annotations, the description carries the full burden and does it well: it discloses that it stops rather than guesses, that dry_run defaults to True, that the two gates are independent and named for their consequences, and that it stops for a human. It does not describe what state a stopped run leaves the editor in or any permission requirements, which keeps it short of a 5.

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

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

The operative information is front-loaded and the Args/Returns block is well organized, but the prose leans rhetorical ('IT STOPS RATHER THAN GUESSING', 'THE TWO GATES ARE SEPARATE ON PURPOSE') and the aside about existing only through one wizard tool is historical noise an agent does not need to decide.

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?

An output schema exists so return values needn't be explained, and the description still summarizes the key result fields (committed, stopped_for_a_human). For a six-parameter reactive driver with no annotations, the stop conditions, defaults, and gate semantics cover what an agent needs to call it safely.

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

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

Schema description coverage is 0% but the Args section documents all six parameters with meaning beyond the names: intent's two accepted values, the distinct consequences of allow_commit vs allow_confirm, dry_run's default and effect, and the units/role of wait_first and budget.

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 line states the action precisely — reactively answer dialogs until none remain — and the body explains the read/classify/press loop, which is unambiguous. It does not distinguish itself from single-step siblings such as app_press_dialog_button or app_list_open_dialogs, leaving the agent to infer the boundary.

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 (this is the loop that drives a sequence of dialogs after firing a command), and the dry_run paragraph gives a clear 'try this first' recommendation. However, no sibling tool is named as an alternative for one-shot presses or read-only inspection, and there is no 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?

With no annotations, the description carries the full burden and largely meets it: it discloses that the state lives in Altium's PCB server (survives restarts), that it is not routine cleanup, that it is idempotent-safe, and that it does not itself save. It does not say what happens to the in-flight transaction's changes when the unwind occurs, which is the one behavioral fact an agent might still need.

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

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

The critical trigger and the follow-up instruction are front-loaded and the follow-up is stated up front. However, the dated case study ('MEASURED on 2026-08-25... lib_link_3d_model faulting between PreProcess and PostProcess') and the AltiumScriptCentral/VBS aside are narrative padding that does not change how an agent calls the tool.

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

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

For a zero-parameter recovery tool with an output schema, this covers trigger, persistence, safety of a false positive, and the required post-step. The only gap is that the return value is summarized but the agent is not told what to do with per-server acceptance failures.

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 nothing for the description to disambiguate; baseline 4 applies. The description correctly conveys that invocation is unconditional and needs 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?

Opens with a specific verb+resource ('Close a transaction') and immediately scopes it to the precise failure state ('a crashed handler left open'). It further anchors the purpose to the exact user-visible symptom ('A command is currently active and save cannot be completed'), which no sibling tool addresses.

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 condition (saves being refused), an explicit non-cost for a false positive ('Calling it when nothing is outstanding is harmless'), and an explicit follow-up sequence ('Run app_save_all afterwards and check still_dirty'). It also warns that Escape and restarts do not resolve the state, so alternatives are ruled out.

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

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

With no annotations, the description carries the full burden and mostly delivers: it discloses that the call verifies the resulting state and pre-empts a likely misreading of the 'changed' flag by saying false means already-in-that-state and is still a success. It omits preconditions such as whether the owning dialog must be open or focused, and what happens when control_label or node_name is not found.

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 operative sentence, followed by a short rationale block and compact Args/Returns sections. Every line is scannable and the motivation paragraph earns its place by explaining why a dedicated tool exists. No filler or repeated boilerplate.

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 4-parameter UI-automation tool with an output schema, this covers the essentials, and the Returns block adds interpretive value about 'changed' rather than merely restating field names. The remaining gap is failure behavior: nothing says what an 'ok': false or a missing control implies, which matters for an automation step that may be chained.

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

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

Schema description coverage is 0%, so the description must compensate and it does: all four parameters are explained, including matching semantics for node_name ('matched by name') and the conditional meaning of dialog_title. It does not restate the schema default of true for expand, nor say whether name matching is exact or case-sensitive.

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

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

The first sentence gives a concrete verb pair and resource: open or close a node in a tree, with the added guarantee of verifying state. The follow-up paragraph explains the gap it fills (trees were readable but not openable, so nested items were invisible), which makes the intent unambiguous. It does not name or contrast with siblings such as app_activate_row or app_set_dialog_control, so it falls short of a 5.

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

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

Usage is implied rather than stated: you reach for this when nested content in a tree is inaccessible because the node is collapsed. The dialog_title note ('which dialog, when several are open') gives a light situational cue. There is no explicit when-not guidance and no routing to alternative UI tools for non-tree controls.

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

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

With no annotations the description carries the full burden, and it does deliver a genuinely non-obvious caveat: the 'modified' flag is unreliable, so false is a floor rather than proof of a clean file. It also documents the empty-dict edge case when no document is active. It stops short of stating that the call is side-effect free or whether an attach/session is required, which would complete the picture.

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 purpose sentence followed by a compact field list, with the important caveat placed on the field it qualifies. The returns block partially duplicates the existing output schema, but the items earn their place by adding semantics (especially the 'modified' reliability note) rather than restating types.

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-argument getter with an output schema, the definition covers purpose, return shape, the unreliable-flag caveat, and the no-active-document case. The one gap is environmental context — whether the caller must be attached to an app instance and what happens across schematic/PCB/library contexts.

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

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

Zero parameters, so there is nothing to disambiguate; baseline 4 applies. The description correctly implies no arguments are needed and cannot mislead about them.

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

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

States a specific verb+resource: fetch info about the currently focused document, and enumerates the returned fields. It does not distinguish itself from nearby siblings that also surface document context (app_list_documents, obj_get_document_info, proj_get_focused), so an agent must infer which to pick.

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

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

Usage is only implied by the name and the phrase 'currently active (focused) document'; there is no explicit 'use this when X, use app_list_documents when Y'. The classic drop-in case exists (resolving what the user is looking at), but the agent has to reason it out.

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

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

With no annotations, the description carries the full burden and does disclose a real behavioral trait: text-only extraction, with an empty string returned when the clipboard is empty or holds non-text data. That edge-case contract is genuinely useful for callers parsing the result, though it doesn't mention any app-attachment prerequisite or whether the clipboard is left untouched.

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 blocks, purpose first, then the return contract. No filler, no restatement of the title, and the most decision-relevant information leads.

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 tool this is essentially complete, and the tool has an output schema that already covers the return shape, making the "Returns:" block redundant but harmless. 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?

The tool takes zero parameters, so there is nothing for the description to clarify and the baseline of 4 applies. No misleading parameter guidance is present.

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 ("Get text content from the Windows clipboard"), which is unambiguous and distinguishes it from the many UI/dialog automation siblings. It does not explicitly contrast with any sibling, but no other tool in the list touches the clipboard, so the resource itself is the differentiator.

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 usage context ("useful for reading data copied from Altium dialogs or reports") but never states when to prefer this over alternatives such as app_read_window, app_read_panel, or app_screenshot for extracting text from the UI. Usage is implied rather than prescribed.

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

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

With no annotations, the description carries the full burden. It does disclose a genuine behavioral trait — values are null when no PCB or schematic is open — and "Get" implies a non-mutating read. It does not say whether values reflect live editor state or persisted document state, nor whether reading has side effects on the active document.

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 opening sentence and the null-value clause are front-loaded and earn their place. The trailing "Returns:" block restates the dictionary structure that the output schema already fully specifies, so it is largely redundant padding.

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 with a full output schema, the description covers what is read, from where, and the degenerate no-document case. Nothing an agent needs in order to call it correctly is missing; the only shortfall is guidance on when this tool is the right choice among the many app_* siblings.

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; there is nothing to disambiguate. The description correctly does not invent parameter guidance, and the scope-selection condition (active board vs. active schematic) substitutes meaningfully for what would otherwise be a 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+resource ("Get ... preferences") and narrows the scope precisely: PCB snap grid/display unit from the active board, schematic visible/snap grid from the active schematic. An agent knows exactly what comes back. It does not, however, distinguish itself from near-siblings such as app_get_status or app_get_version.

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

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

Usage is only implied: the null-value clause implies the tool is meant to be read while a board or schematic is open, which is a useful precondition. But there is no explicit when-to-use statement, no exclusion, and no pointer to an alternative (e.g., a setter counterpart or a status tool).

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

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

No annotations are provided, so the description carries the behavioral burden. The phrase 'without touching the design' signals a read-only diagnostic, and the return list discloses key outputs including round_trip_ms being None when Altium is down. It does not explicitly clarify whether workspace files are only read or how auth/error conditions behave, leaving some transparency gaps.

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

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

The purpose is front-loaded, and the description is organized into scope, diagnostic details, and returns. It is somewhat verbose because the Returns section repeats fields likely present in the output schema, but the parenthetical about stale request files adds useful diagnostic meaning.

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

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

For a zero-parameter diagnostic tool with an output schema, the description is largely complete: it explains what is checked, that it does not touch the design, and what key return fields mean. It could be stronger by clarifying side effects on workspace files, permission assumptions, and explicit routing among sibling diagnostic tools.

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

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

This tool has zero parameters and the input schema is an empty object, so there are no parameter semantics to explain. The baseline for a no-parameter tool is 4, and the description does not need to compensate for any schema gaps.

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: it reports health of the MCP bridge, workspace, and Altium link, and enumerates diagnostic signals such as version match, IPC round-trip time, and workspace file counts. It is clearly a diagnostic snapshot tool, but it does not explicitly contrast itself with nearby siblings such as app_get_status, app_ping, or app_diag_workspace.

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

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

It gives clear usage context: one call to diagnose plumbing without touching the design, and it explains that stale request files indicate a dead or wedged poller. However, it does not name an alternative tool or explicitly state when not to use this one, so it falls short of the highest level.

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

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

With no annotations at all, the description carries the full burden and does so well: it discloses the multi-instance selection algorithm (bridge status window owner, else the only visible window), the exact ambiguity failure mode (pid=None, ambiguous=True, reason populated, UI tools refuse), and that other_servers only produces warnings without stopping anything. These are non-obvious behavioral traits an agent could not derive from the empty parameter schema.

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

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

Front-loaded with the core purpose and the return field list, with the more specialized multi-instance and multi-server caveats after. The trailing 'Returns: Dictionary with status information' is pure redundancy given the bulleted list and the output schema, and the bullets duplicate schema-documented fields.

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

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

For a zero-parameter, read-only status probe with an output schema, the description covers the parts the schema cannot: instance disambiguation, refusal behavior under ambiguity, and the advisory-only nature of other-server warnings. Nothing needed to call or interpret 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; there is no parameter meaning to add or omit. The description instead spends its space on return-value semantics, which is appropriate 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: 'Check if Altium Designer is running and get status information', then enumerates exactly what status means (running, PID, executable path, bridge attachment). It does not explicitly differentiate itself from nearby siblings such as app_ping, app_context, or app_diag_workspace, so it falls short of a 5.

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

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

Usage is only implied: an agent can infer this is a preflight/health check before invoking UI tools, and the note that 'every UI tool refuses' when ambiguous hints at the dependency. However, there is no explicit 'use this instead of X' routing against app_ping, app_context, or app_get_version, and no stated preconditions.

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

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

With no annotations present, the description carries full burden and does add real behavioral context: it discloses the internal dependency on Client.GetProductVersion and, importantly, the degraded-mode behavior where 'version' is omitted and a 'note' field appears instead. That failure-mode disclosure is exactly the kind of non-obvious trait the description should surface; only permission/auth and cost details are absent.

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 purpose sentence followed by a short fallback caveat and a Returns block. Slightly redundant to restate return keys when an output schema exists, but the text is short and each sentence carries information.

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

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

For a no-arg read tool with an output schema, the description covers what an agent needs: what it returns and the important case where the version key is missing. The returns enumeration duplicates the output schema somewhat, but the fallback caveat is genuinely additive.

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

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

Zero parameters, so there is nothing to disambiguate; baseline 4 applies.

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

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

States a specific verb and resource: 'Get the version of Altium Designer.' That is unambiguous and distinguishable from most siblings, though it never explicitly contrasts with the nearby app_get_status, which could plausibly also report version information.

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 (you'd call it when you need the host application version, e.g. for diagnostics or compatibility checks), but there is no explicit when-to-use/when-not-to-use guidance and no mention of app_get_status as an alternative.

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

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

With no annotations, the description carries the full burden and does most of it: it states that operations move no pointer, take no focus, and cannot hit the wrong element, and it spells out both success ("ok" plus dialog_closed) and failure (refusal naming the missing pattern plus the element rectangle) shapes. It omits any warning that a press mutates application state and may be destructive or non-reversible.

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 action statement is front-loaded and the Args/Returns blocks are tight and scannable. The MSAA-vs-UIA paragraph and the dispatcher example are longer than strictly needed, though both do carry real selection 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 four-parameter mutation tool with no annotations, the definition covers mechanism, scope, parameter meaning, and both return branches, and an output schema exists so return values need no further elaboration. Missing only environmental caveats such as permission or timing/threading expectations.

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 0%, so the description must document all four parameters itself, and it does: name (element name or automation id, with Button preferred over a same-labelled label), dialog_title (empty means frontmost dialog, else main window), text (set value instead of pressing), and expand ("true"/"false" to open or close a node, which also explains why the parameter is a string rather than a boolean).

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

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

Opens with a specific verb set and resource: press/set/expand an element via UI Automation patterns, and the body makes clear this is a pattern-based action rather than a synthetic mouse click. It never names the closest siblings (app_press_dialog_button, app_set_dialog_control, app_expand_tree_node), so the boundary with those is left to inference, which keeps it out of 5 territory.

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?

"That makes this the right tool for a WPF dialog, and for anything you want done while the user keeps working" gives a clear selection criterion, and the Returns section explains the refusal path that tells you when to fall back to a real click. It stops short of naming the alternative tools that would be used 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?

With no annotations provided, the description carries the burden but only partially: it discloses workspace scoping and newest-first ordering, yet does not state that the call is read-only/non-mutating or whether checkpoints expire. It never contradicts the (absent) annotations, so no flag.

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

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

One sentence, zero waste, with the resource front-loaded and the ordering qualifier appended. Nothing redundant or padded.

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

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

For a zero-argument read tool with an output schema already covering return shape, the description supplies scope and ordering, which is nearly everything an agent needs. Only the read-only nature 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?

The tool takes zero parameters, so the baseline is 4; there is nothing the description could add beyond the workspace scoping it already mentions.

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

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

States a specific verb ('List') and resource ('saved checkpoints') plus the scope ('current workspace') and ordering ('newest first'), which distinguishes it from app_restore_checkpoint and app_checkpoint by name alone.

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 before app_restore_checkpoint, but the description never names that alternative or states when to prefer it over, say, app_list_documents. No exclusions or prerequisites are given.

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

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

With no annotations, the description carries the full burden and does well: it explains that `loaded` separates on-disk project membership from editor-resident state, and warns that `modified` is a floor rather than a clean bill because it doesn't always propagate from ProcessControl. It never explicitly states that the operation is read-only or whether an attached session is required.

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 opening sentence is well front-loaded, but the long Returns block enumerates file_name, file_path, and document_kind, which an existing output schema already covers. Only the `loaded` and `modified` commentary earns its place; the field-name bullets are redundancy.

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

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

Because an output schema exists, the return values needn't be restated, and the description supplies the semantic and reliability context an agent actually needs (loaded vs. resident, modified unreliability). The one meaningful gap is the absence of any contrast with proj_list_documents, which leaves a real sibling ambiguity unresolved.

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, which is the baseline-4 case; there is nothing for the description to disambiguate at the input level.

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 all documents known to the current Altium workspace") and clarifies scope by naming both project members and free documents. It never distinguishes itself from the sibling proj_list_documents, so an agent cannot tell the two apart from the description alone.

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

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

Gives concrete routing guidance: project-scope queries like query_objects/batch_modify only iterate loaded sheets, so call load_project_sheets first when `loaded` is false. That is real when-to-use advice, but it covers downstream follow-up actions rather than when to prefer this tool over proj_list_documents.

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

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

With no annotations, the description carries the full burden and does so: it discloses that the tool reads the Win32 process rather than the bridge, explains how blocked is derived, and warns that blocked:false does not prove the UI is alive, citing a real failure mode. "Reads only. Presses nothing." gives a clear safety profile, and the has_unreadable_content caveat prevents a false negative interpretation.

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

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

The critical routing sentence is front-loaded, and the dialog kind taxonomy is structured as a scannable list. It is longer than strictly necessary for a no-argument tool, with some repetition around the blocked semantics, but nearly every sentence 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 diagnostic tool with an output schema, the description covers everything an agent needs: when to call it, how to interpret blocked, what each dialog kind means, what data is missing by design, and what the call does not do. Nothing necessary for correct invocation or interpretation is absent.

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

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

Zero parameters, so baseline is 4; nothing in the schema needs interpretation. The description does not need to say more because calling it requires 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?

Opens with a concrete verb+resource framing ("What Altium has on screen, what it says, and if it is stuck") and the tool name is immediately grounded in listing open dialogs. It is clearly separable from read-only UI siblings like app_read_window or app_ui_snapshot because it states it bypasses the bridge entirely.

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 TOOL TO REACH FOR WHEN THE BRIDGE GOES QUIET" is an explicit selection rule, and the description explains why other tools cannot serve that case. It also names an alternative path ("Read the Messages panel for the change list") when grid content is unreadable, so the agent knows where to go next.

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

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

With no annotations supplied, the description carries the full behavioral burden and does so well: it explains that the default operation reports visible docked panels, that `offered_too` requires a real menu click and steals focus, and that an empty result can occur because panels are found by tab and may be reported empty on AD 25. These are exactly the side effects and caveats an agent needs before invoking it.

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

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

The description is front-loaded and organized into clear prose, Args, and Returns sections. It is slightly long for a one-parameter list tool, but nearly every sentence adds useful distinction, caveat, or parameter context.

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

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

The tool's complexity is modest, and the description covers the key distinctions, optional behavior, side effect, and empty-list caveat. Since an output schema exists, the return format need not be explained, but the description still provides useful confirmation of the response shape and caveats.

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?

Although schema description coverage is 0%, the description fully compensates for the single parameter by explaining that `offered_too` reads what View > Panels lists, representing what could be opened rather than what is open. It also explains the focus-stealing consequence and confirms the default is off.

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 clearly identifies the resource as Altium's currently visible dockable panels and explicitly distinguishes it from `app_list_open_dialogs` by explaining that panels are child windows, not top-level dialogs. The examples of Projects, Navigator, PCB, Properties, and Messages make the scope concrete.

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 a clear usage distinction against `app_list_open_dialogs`, explaining why that sibling missed docked panels. It also clarifies when to enable `offered_too` for potentially openable panels versus currently open panels. It does not explicitly route to related tools like `app_read_panel`, but the primary usage context is well established.

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

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

No annotations exist, so the description carries the full burden and does: it discloses that the tool steals focus like any menu click, that it reaches a panel only via View > Panels because no scripted API exists, that menu entries are toggles so re-clicking would close a panel, and that an unverifiable result triggers a second click reported as `toggled_back`. That is unusually complete disclosure of side effects and failure modes for a mutation-by-UI tool.

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

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

The action is front-loaded in the first clause, followed by rationale, edge cases, then Args/Returns sections. Some middle prose ('Those menu entries are toggles...' and the toggled_back explanation) is dense but each sentence carries a distinct behavioral fact. Slightly verbose for a 2-parameter tool but not padded.

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

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

An output schema exists, yet the description still usefully spells out the reply shape including `opened` meaning false when already present and the `toggled_back` case, and it covers the focus side effect that no annotation declares. The one thing an agent still needs but cannot find here is how to discover a legal panel name or the prerequisite application state.

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 0% (bare types plus a default of 1.2), so the description must compensate, and it does: `name` is defined by its exact source ('as View > Panels spells it') with four concrete examples, and `settle` is explained as 'how long to allow for it to appear'. The only gap is that settle's unit (seconds) is left to be inferred from the default value.

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

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

The first sentence gives a specific verb and resource ('Open a dockable panel by name, and confirm it appeared') plus the verification side-effect, and the text later distinguishes itself from the read path ('Reading a panel afterwards does not [steal focus]'). It never names the sibling that lists valid panel names (app_list_panels) or app_read_panel directly, so sibling differentiation is implied rather than stated.

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

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

It states the key operating conditions: already-open panels are reported, not clicked, and 'Calling again does not help in that case.' That is genuine when/when-not guidance for the retry case. It lacks guidance on how to obtain a valid panel name (presumably app_list_panels) and on prerequisites such as an open document.

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

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

With no annotations, the description carries the full burden and does so well: it explains that nothing here refuses or stops anything, that warnings are advisory only, that version_match can describe a file Altium did not load, and it names the exact remedy sequence (close/reopen the script project, note that re-running StartMCPServer or restarting Altium may not suffice). It also discloses the known limitation that SCRIPT_VERSION only speaks for Main.pas.

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 stale-cache guidance are front-loaded and earn their place, but the bulk of the text is a per-field enumeration of return values that duplicates an existing output schema. The SCRIPT_VERSION/unit-stamp digression is useful but could be compressed.

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 diagnostic tool, the description covers failure modes, cache staleness, and the meaning of ambiguous fields such as script_location_match and stale_units. It is complete on return-value semantics; the only gap is routing guidance relative to sibling diagnostics.

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

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

Zero parameters, so the baseline of 4 applies; the schema has nothing that needs semantic elaboration.

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 action (test whether the Altium script is responding) and the resource it inspects (Altium Designer, the Altium_API.PrjScr script, file-based comms), plus the version stamp. It does not distinguish itself from nearby siblings like app_get_status, app_get_version, or app_diag_workspace, so the agent must infer which diagnostic to pick.

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 three numbered verifications and the stale-cache advice imply this is the first-line health/diagnosis call, but the description never says 'use this before X' or 'prefer app_get_version for Y'. No alternative is named despite several plausible siblings.

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

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

With no annotations, the description carries the full behavioral burden: it discloses Win32 window-handle addressing, operation while Altium is blocked, caption normalization (ampersands/ellipsis), and the safety gate that refuses committing presses unless allow_irreversible is set.

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 well-structured with Args/Returns sections. Some backstory ('The missing primitive... buried inside a single task-specific driver') and emphasis ('That is the whole point') are less essential, but most text earns its place.

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

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

Complete for a three-parameter UI action with an output schema: parameters, matching rules, blocking behavior, irreversible-press policy, and return contents are all covered. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 0%, yet the description documents all three parameters: button_caption as the visible caption, dialog_title as a substring selector with an empty-string default, and allow_irreversible as the gate for committing presses. This fully compensates for the absent schema descriptions.

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

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

States a specific verb and resource: 'Press ONE named button in an open Altium dialog.' The contrast with app_set_dialog_control (checkboxes) and app_drive_dialogs (sequences) makes the scope unambiguous even among many UI 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 says to use app_drive_dialogs for a whole sequence rather than one press, and explains that this tool is for the blocked-modal case where the scripting bridge is unavailable. It also states the caption-matching rule and irreversible-press gating, leaving little to infer.

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

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

With no annotations, the description carries the full burden and does so: it declares the operation is non-focus-stealing and non-mutating, warns that the read is complete but slow with concrete numbers (lazy accessible tree, ~116 ms per node, 162 rows ≈ 30 s), and justifies the tradeoff ('slow and complete beats fast and partial'). That latency warning is the single most decision-relevant fact for an agent and would otherwise be invisible.

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

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

Front-loads purpose, then precondition, then cost, then return shape — a sensible order with no filler. Minor redundancy in 'takes no focus and moves nothing' (two phrasings of the same non-intrusiveness point) and the parenthetical return block is longer than needed given an output schema exists.

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

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

For a read tool with no annotations, one parameter, and an existing output schema, this covers safety, prerequisites, cost, and even why grids are reported separately. The only real hole is the undocumented `name` argument, which is the one thing the agent must supply to call it successfully.

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

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

Schema description coverage is 0% for the single required `name` parameter, and the description never explicitly says the parameter is the panel name that comes from app_list_panels (or what format/identifier it takes). The connection is strongly implied by the workflow guidance, but an agent still has to infer the argument's source and shape.

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 ('Read what is inside an open panel') and immediately scopes it ('Reads the WHOLE panel'), which separates it from partial-read siblings like app_read_window or app_ui_snapshot. It also names the related tools (app_open_panel, app_list_panels) so the agent can place it in the workflow 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 an explicit precondition ('The panel must already be open') and names the exact alternatives to satisfy it ('use app_open_panel first, or app_list_panels to see what is there'). It also states the operating condition where this is appropriate ('safe while a user is working'), leaving no inference needed about when to reach for it.

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

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

With no annotations, the description carries the full disclosure burden and does a real job: it explains the visibility ceiling (TLabel text exists only as pixels), why that ceiling exists (no handle, no accessible object), and that WPF elements can be acted on via app_invoke_element. It does not state that the call is a pure read with no side effects, nor any auth/attach or timing requirements.

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

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

The first line is a clean, front-loaded statement of purpose, but the middle is project history and rationale ('THE LAYER THAT WAS MISSING. This project read Altium three ways...') that is longer than the actionable content. The 'Returns' block restates the output schema verbatim, spending space on information the agent already has.

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?

Return shape is covered by the output schema and limitations are well explained, but for a zero-required-parameter, zero-schema-documentation tool the description leaves the two knobs unexplained and never says how to discover or target the window in the first place. An agent knows why it would call this, but not precisely how to parameterize it.

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

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

Schema description coverage is 0% and the description says nothing about the two parameters. It never explains that dialog_title selects which window is read (or what the empty default means), nor what with_text controls despite the returned 'text' array being its obvious output — an agent must guess at both.

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 line gives a specific verb and resource ('Read a window through UI Automation') and the middle section makes concrete what it returns (elements with name/type/automation_id/enabled/rect and text). It differentiates itself from MSAA and OCR-based reading and from app_screenshot, but never mentions the plausibly similar sibling app_ui_snapshot or app_read_panel, so sibling differentiation is only partial.

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

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

It states the decisive use case explicitly — Altium's WPF dialogs whose buttons are not child windows — and names the alternative with the condition that selects it ('Delphi's TLabel ... Use app_screenshot there'). What is missing is prerequisite context such as needing an attached session (app_attach) or how to pick a dialog among several open ones.

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

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

With no annotations, the description carries the full burden and does so: it discloses that design files are overwritten, that a reload prompt may appear, that Altium holds documents open, and precisely what prune_added destroys (files created after the checkpoint). The destructive vs. non-destructive default is spelled out explicitly.

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

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

Front-loaded with the operation and its risk, then the precondition, then the parameter nuance. The Args/Returns block is compact and every sentence adds information that isn't duplicated 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 two-parameter mutation tool, all decision-relevant information is present: risk profile, precondition, parameter semantics, and the source of the id. An output schema already exists, so the brief Returns note is a bonus rather than a necessity.

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 0%, and the description fully compensates: checkpoint_id is documented as coming from app_list_checkpoints, and prune_added's meaning, effect, and default are described in terms the bare boolean schema does not convey. No parameter is left ambiguous.

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 ('Restore the focused project's files from a checkpoint') with an explicit scope (the focused project) and immediately names what it overwrites. An agent can distinguish it from app_checkpoint and app_list_checkpoints 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 a clear operational precondition ('Close the project in Altium ... before restoring, since Altium holds documents open') and points to app_list_checkpoints as the source of the id. It does not explicitly state when not to restore or contrast with app_checkpoint, so it falls 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?

No annotations exist, so the description carries the full burden and does so thoroughly: it discloses that RunProcess fails silently, that success is indistinguishable from a typo, and cites a measured 2026-08-17 case (0.11s, success:true, no dialog). It also declares the refusal contract (UNMAPPED_MENU_PATH) and that outcome_verified is always false.

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 load-bearing caveat and the sibling routing are front-loaded in the first three paragraphs. The historical note about the old MenuID fallback is somewhat verbose, but it justifies the refusal behavior rather than padding.

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

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

Covers the full call contract for a one-parameter mutation-adjacent tool: valid inputs, refusal behavior, the meaning of the response fields, and the fallback tool. Nothing an agent needs in order to call this correctly is missing, despite the output schema already existing.

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 0%, so the description must compensate and it does: menu_path is documented as pipe-separated with an example, and the eight accepted paths are enumerated with the explicit statement that everything else is refused. This is effectively an enum the schema lacks.

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 ("Dispatch a menu command by path") and immediately scopes it with "DISPATCH IS NOT EXECUTION." It distinguishes itself from app_click_menu and app_run_ui_command by naming the sibling that actually performs execution, so an agent can route 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?

Explicitly names the alternative (app_click_menu) and the condition that selects it: "when you need the command to actually happen." It also enumerates the exact set of mapped paths and states that anything else is refused with UNMAPPED_MENU_PATH, leaving no inference required.

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

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

With no annotations, the description carries the full burden and does: it discloses that firing a modal-opening command blocks Altium's scripting engine, why it cannot be split into two bridge calls, that allow_commit defaults OFF so changes are presented rather than executed, that focus may be stolen, and that a mismatched dialog causes failure at the menu stage.

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 and the key routing advice, and the Args/Returns structure is scannable. The third paragraph ('Doing this by hand meant arming a watcher process...') largely restates the split-call point already made, so a sentence or two could be cut.

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

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

For an eight-parameter, mutating, focus-stealing UI composite with no annotations, the description covers invocation, gating defaults, failure semantics, and the AND-combination of the ok flag. An output schema exists, so the Returns section is supplementary rather than a gap-filler.

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 0%, so the description must compensate, and it documents all eight parameters in Args — including units (seconds for wait_first and budget), the pipe-separated menu path with a worked example, a discovery pointer (app_click_menu with list_only=True), and the safety default for allow_commit and allow_confirm.

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 line states a specific verb+resource: invoke a menu command AND answer the dialogs it raises. It immediately positions itself relative to siblings as 'the composite, and usually the one to reach for', and the blocking rationale explains why it exists alongside app_click_menu / app_drive_dialogs.

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 a clear default recommendation ('usually the one to reach for'), explains the modal-blocking condition that forces the composite, and contrasts its dry_run default with app_drive_dialogs. It stops short of an explicit 'when not to use this' (e.g. use app_click_menu when no dialog is expected), leaving that to be inferred from expect_dialog.

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

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

With zero annotations the description carries the full burden and does so: it explains that mutation tools now write in-memory only, that Altium silently refuses saves while a command is active, that saved:true was previously misleading, and that saved is now false when anything remains dirty. The remediation (run app_exit_active_command and retry) is a level of operational detail rarely seen.

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

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

The purpose is front-loaded in the first sentence and the material is well organized into purpose, when-to-call, caveat, remedy, and returns. It runs long and the "MEASURED" anecdote about the past bug is slightly padded, though it does justify the still_dirty warning.

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?

Everything an agent needs to call this correctly is present: trigger points, the silent-failure mode, how to detect it, and how to recover. The output schema covers return shape, and the description still summarizes it, so no gap remains.

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 and there is nothing for the description to disambiguate. It additionally names the return keys (saved, still_dirty, reason), which is bonus context even though an output schema exists.

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?

"Flush every dirty Altium document to disk" gives a specific verb plus resource and scope (all documents, dirty only). It implies the distinction from the sibling app_save_document via "every," but never names that sibling explicitly, leaving a small inference step.

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 invocation points are listed: logical checkpoints, after a routing pass, before DRC, before closing. It also states when NOT to rely on it ("Detach also triggers save_all automatically, so you don't need this as the very last step") and gives a retry procedure when saves are refused.

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

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

With no annotations provided, the description carries the full burden and succeeds. It discloses non-obvious behavior: `saved` is inferred from file age on disk because Altium does not report declined saves, `was_modified` misses script-made edits, focus/workspace are untouched, and command-active declines return `saved` false with a retry path.

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

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

The description is front-loaded with purpose and sibling differentiation, then structured into behavioral caveats, Args, and Returns. Despite its length, every sentence adds operational value without redundant restatement.

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?

An output schema exists, but the description still adds useful semantic meaning to return fields (`saved`, `was_modified`, `reason`, `NOT_OPEN`) and edge cases. For a one-parameter save tool with no annotations, this is complete enough for an agent to call it correctly.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: `file_path` is defined as an absolute path to an open document, and the empty-string default is explained as saving the focused document.

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?

Starts with a specific verb and resource: 'Save ONE open document: file_path, or the focused one.' It explicitly distinguishes itself from sibling `app_save_all` by contrasting single-document and all-document behavior.

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 selection guidance against `app_save_all`: the sibling may stop a save you never asked for when any one document cannot be written, while this tool touches only the named document. It also gives a concrete remediation workflow for declined saves during an active command.

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

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

With no annotations, the description carries the full burden and does disclose the non-obvious behaviour: it writes a file to disk (defaulting to the workspace directory), returns a JSON envelope with path and hwnd, and the agent must then read the file to actually see anything. It does not cover capture limits such as window size, off-screen or minimised windows, or multi-monitor behaviour, which are the obvious failure modes for a screenshot tool.

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

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

The opening sentence and the Args/Returns block are front-loaded and efficient. The middle paragraph, however, is a developer-facing rationale about ui/ocr.py and the history of the tool — it justifies the tool's existence to a human reviewer rather than helping an agent decide or call it, and it inflates the definition considerably.

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, zero-required capture tool this is close to complete: destination, dialog targeting, return shape, and the crucial 'read the file afterwards' step are all stated. Since an output schema exists, the Returns block is partly redundant, but the pointer to read the PNG is real added value. Missing only edge-case behaviour for unusual 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 description coverage is 0%, so the description must compensate entirely, and it does: path is explained as the PNG destination with the workspace-directory default and the reason for it, and dialog_title is explained as selecting a dialog instead of the main window. Both of the two optional parameters gain meaning the bare schema does not provide.

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

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

The first line gives a specific verb and resource: capture the Altium window, or a single dialog, into a PNG file. That is clearly distinguishable from neighbouring tools such as app_read_window and app_ui_snapshot, since the output is an image rather than a text tree, though the description never names those siblings explicitly. The purpose is unambiguous but the differentiation is implied rather than stated.

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

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

The description gives a concrete usage rationale: use it when judgements must come from what is drawn on screen rather than from an accessibility tree that omits rendered elements — greyed controls, rendered dialog text, which page is in front. It does not name alternatives or state when not to use it, so an agent must infer that app_read_window/app_ui_snapshot remain the cheaper first choice for tree-visible content.

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

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

With no annotations present, the description carries the full load and does add real behavioural context: the virtualisation caveat, the sign semantics, and the crucial disclosure that 'moved: false' at the end of a list is a valid result rather than an error. It omits what happens on an unknown control_label, whether scrolling is animated/settled, and any permission or timing expectations.

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

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

Purpose is front-loaded, which is good, but the all-caps emphasis and the long DevExpress-virtualisation sentence are wordier than the point requires. It is readable and mostly earns its space, yet could be trimmed without losing meaning.

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

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

An output schema exists, so return-format detail is not required, and the description wisely flags the one ambiguous return signal ('moved'). However, for a UI-automation tool with no annotations and no schema descriptions, the description leaves too much unsaid about the required identifier and the failure modes to be called complete.

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

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

Schema description coverage is 0%, so the description must compensate and largely does not. It explains the sign of the scroll amount but never names the 'lines' parameter, and gives no meaning for the required 'control_label' or for 'dialog_title' (e.g. how a control is identified inside a dialog). An agent still cannot resolve three of three parameters from prose.

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 set ('Scroll a list, grid or tree') so an agent knows exactly the action and target. It does not name or contrast with the closest siblings (app_read_panel, app_expand_tree_node, app_activate_row), leaving that disambiguation to the agent's judgement.

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 motivating context: virtualised controls only expose on-screen content, so scrolling is needed to reach rows that 'did not exist' to a caller. Sign convention ('positive scrolls down, negative up') is stated. There is no explicit 'use this instead of X' routing, so it stops short of a 5.

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

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

No annotations exist, so the description carries the full burden, and it does: it warns the keystroke goes wherever focus is, states there is no read-back ('the reply says what was sent and never that it worked'), and documents the failure mode for unknown key names. These are exactly the behavioral traits an agent needs before invoking a focus-dependent input 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?

Front-loaded with the action and the keyboard-vs-control distinction, then syntax, then the focus caveat — a sensible order. The all-caps framing line and poetic spacing are stylistic flourishes that cost some density, but no sentence is redundant.

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

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

Single-parameter tool with an output schema available and no annotations; the description still covers invocation format, preconditions (focus), and postconditions (no verification of success). Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it does thoroughly: space-separated token syntax, '+' chord notation, three worked examples, an explicit modifier list, an explicit key list, and the refusal behavior for unknown names. This adds substantial meaning beyond the bare `sequence: string` schema.

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

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

States a specific verb and resource: 'Send a key sequence to whatever currently has focus.' It also explicitly differentiates itself from siblings ('Every other tool here addresses a control; this addresses the keyboard'), so an agent can route between this and app_type_text or app_set_grid_cell without opening the schema.

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

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

Gives concrete when-to-use cases (canvas shortcut, grid that commits on Enter, dialog answered with Escape, chords) and names prerequisites/alternatives: 'Establish focus first, with app_click_menu or app_open_panel, and check the result afterwards.' That is explicit routing guidance, not implied usage.

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

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

With no annotations, the description carries the full burden and does not meet it. It says 'Returns: Dictionary with result of the operation,' which discloses nothing about failure modes (missing file, unopened document), whether the call is idempotent, or whether it changes visible UI focus.

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 sentence is front-loaded and wastes no words. The Args/Returns block is generic boilerplate, and the Returns line adds little since an output schema already exists, but the overall length is appropriate.

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 output schema covers return values, so the vague Returns line is not a real gap. What remains missing for a lone-parameter state-changing tool is error and prerequisite behavior, and that is left unstated.

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

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

Schema description coverage is 0%, so the schema offers only the title 'File Path.' The description does add meaning by specifying a full path to the document to activate, distinguishing it from a bare filename, but it gives no format example, extension expectations, or behavior for relative paths.

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: 'Set a specific document as the active (focused) document.' This clearly separates it from the read-oriented sibling app_get_active_document and app_list_documents. It stops short of naming siblings explicitly, so a 4 rather than a 5.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no alternatives named. The only hint is the phrase 'active (focused) document,' which leaves prerequisites such as whether the target document must already be open entirely 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?

With no annotations, the description carries the full behavioral burden and does so well. It discloses verification/read-back semantics, failure reporting for silent no-op clicks, refusal behavior for disabled controls and radio-off requests, and idempotent 'changed: false' behavior for already-set states.

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

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

The description is front-loaded with purpose, targeting strategy, and safety behavior before the Args section. It is somewhat long and uses emphatic caps and rationale that could be trimmed, but the length is largely justified by the tool's behavioral complexity.

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

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

Given six parameters, no annotations, and no schema descriptions, the description is complete enough to invoke the tool correctly. It also explains return values even though an output schema exists, adding useful behavioral context rather than leaving gaps.

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

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

Schema description coverage is 0%, so the description must compensate for all six parameters, and it does. It explains control_label as a visible label, checked/text as desired state, select_row as name-based row selection, dialog_title as a substring selector, and list_only as a read-only inspection mode.

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: 'Read or CHANGE a control inside whatever dialog is open.' It immediately distinguishes its scope from adjacent dialog-driving tools by explaining that buttons are handled by the dialog driver while this tool handles checkboxes, radios, and fields.

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 clearly framed: use label-based targeting, not positions; use this for controls rather than buttons; use list_only to inspect without changing. It also defines refusal cases (disabled controls, radio-off requests) and idempotent behavior. The only minor gap is that the alternative sibling tool is referred to generically as 'the dialog driver' rather than by name.

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

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

With no annotations, the description carries the full burden and does so richly: it discloses the three fallback routes (default action, accessible selection, real click), that the value is read back so no-op routes are reported rather than silently believed, and the failure shape with 'offered' options. This is exactly the behavioral context an agent needs for a fragile UI automation tool.

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

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

The opening sentence is well front-loaded, but the paragraph about the tool having been 'readable and unsettled' and the metaphor about 'a property that reads and will not write' is historical justification that does not help an agent decide or call. The args and returns sections are useful; the middle prose is padding.

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 4-param UI mutation tool with no annotations, the description is thorough: it explains the attempt strategy, verification, and failure output. An output schema exists so return values needn't be spelled out, and the remaining gap is the absence of sibling routing guidance rather than missing behavior.

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 0%, so the description must compensate, and it documents all four parameters meaningfully: control_label as the combo's label, option matched by name, dialog_title to disambiguate multiple open dialogs, and list_only as report-without-change. This goes well beyond bare names, though it stops short of format examples for control_label/dialog_title matching.

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 an option in a combo box or drop list, and verify it.' This is clearly distinct from siblings like app_set_grid_cell or app_set_dialog_control, which act on different controls. An agent knows exactly what the tool accomplishes.

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 through the args (control_label, dialog_title, list_only) and the read-back guarantee, but there is no explicit guidance on when to prefer this over app_set_dialog_control or app_set_grid_cell, nor any stated preconditions. The caller must infer the selection context.

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

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

With no annotations to lean on, the description carries the full burden and does so: it explains the activate-then-type-then-commit lifecycle, why the value is read off the cell rather than the editor, and the two concrete failure modes (read-only columns, validating columns that revert). That failure profile is exactly the non-obvious behavior an agent needs before committing a 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?

The operative instruction is front-loaded in one short line, followed by context, Args and Returns — good structure. A few sentences are stylistic rather than load-bearing ('A grid cell is not an edit control until it is being edited'), but they justify the activate-first mechanic, so the length is defensible.

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

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

For a 6-parameter, no-annotation mutation tool, everything an agent needs is present: which grid, how the row and column are matched, what happens on commit, and how to preview safely with list_only. An output schema exists, so the Returns block is bonus rather than required, and the success/failure asymmetry (ok:false when the read-back differs) is stated plainly.

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 0%, so the description must document all six parameters — and it does, in an Args block covering control_label, row, column, text, dialog_title and list_only. The rationale for the column parameter (many cells are unnamed, so a numeric index may be the only handle) adds meaning the schema's bare 'string' type cannot convey.

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

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

The first line names a concrete verb and resource — 'Type into one cell of a grid, and read it back' — and the Altium-specific note ('rule and property editors take their input this way') tells the agent exactly which UI surfaces this targets, separating it from generic typing tools like app_type_text.

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 a real precondition for use ('Selecting a row was possible before; changing anything in it was not') and a recommended first step ('list_only: ... Worth doing first, since it shows which columns have names'). It stops short of naming the competing siblings (app_set_dialog_control, app_type_text) explicitly, so the agent must infer that a grid cell is not a dialog control.

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

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

No annotations are provided, so the description carries the full behavioral burden and does so thoroughly. It discloses the exact file written, that the dashboard polls it and shows a banner, that the operation is purely informational and does not affect tool dispatch, the recommended call timing, the empty-string clearing behavior, and the return shape with truncation. This is rich behavioral context beyond what any structured field provides.

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 front-loaded with purpose and behavior, then uses clearly labeled Args and Returns sections. Every sentence adds useful information: mechanism, informational status, call timing, examples, clearing behavior, parameter format, and return value. 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 one-parameter informational tool with no annotations and an output schema, the description is complete. It covers what the tool does, when to use it, side effects, clearing behavior, parameter format, and return value; an agent has everything needed to call it correctly.

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

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

Schema coverage is 0%, so the description must compensate, and it does. It describes the single intent parameter as a short human-readable description, constrains it to one line and <=240 characters, and explains that an empty string clears the banner. These are meaningful semantics not present in the input schema.

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

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

The description uses a specific verb and resource: it tells the dashboard the high-level task the agent is working on. It also clarifies the mechanism (writes workspace/intent.txt for the dashboard banner) and explicitly distinguishes this from operational routing by saying it does not affect tool dispatch. An agent can immediately understand what this tool does and what it does not do.

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 clear guidance on when to call it: once at the start of a long task, with concrete examples of intent text, and notes that an empty string clears the banner. It does not name alternatives such as design_live_note, so the routing context is clear but not exhaustive; a 4 is appropriate rather than a 5.

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

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

With no annotations, the description must carry behavioral disclosure. It clearly states that with no name it lists buttons with rectangles, and with a name it presses the button and reports whether a menu dropped, explicitly noting that many toolbar buttons open menus rather than acting. It does not describe permission requirements or potential destructive effects of pressing, so a 4 is appropriate.

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 four sentences, front-loaded with the core dual action, then context and behavioral detail. Every sentence adds useful information with no redundant or filler text.

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

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

Given no annotations, a simple optional parameter, and an existing output schema, the description covers the essential behavior and return reporting. It omits prerequisites such as ensuring the application is attached, which keeps it from a 5.

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

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

Schema description coverage is 0% for the single optional 'name' parameter, but the description fully compensates by explaining that omitting name lists buttons and providing a name presses that button. This is exactly the semantic distinction an agent needs to invoke the tool correctly.

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

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

The first sentence gives a specific verb ('List') and resource ('toolbar buttons') and states the dual mode ('or press one by name'). It conceptually distinguishes toolbar behavior from the menu framework ('other half of the bar framework the menus use'), but it does not name or route to specific sibling tools like app_click_menu or app_run_ui_command, so it falls short of a 5.

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

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

The description clearly explains the two usage modes based on the optional name parameter and gives a rationale for choosing toolbar actions (commands with no menu equivalent, one-click vs three). It lacks explicit exclusions or named alternatives, so it earns a 4 rather than a 5.

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

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

With no annotations, the description carries the full burden. It usefully discloses that characters (not virtual keys) are sent, so case and punctuation are preserved, and that there is no read-back. But it omits failure behavior: what happens if nothing has focus, or if the focused control rejects input, and whether text appends or replaces.

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

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

The core action is front-loaded in the first sentence, followed by the alternative and behavioral notes, and every sentence earns its place. The line breaks fall mid-sentence, making the raw text read a little choppily, but there is no wasted content.

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

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

An output schema exists, so the description needn't explain return values, and the "no read-back" note signals that nothing is returned. For a one-parameter UI automation tool the coverage is nearly complete, with the remaining gap being explicit handling of the no-focus case.

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 0% for the single "text" parameter, so the description must compensate. Saying it carries punctuation and case because it sends characters rather than virtual keys does clarify that the value is raw literal text rather than a key-name syntax, which is meaningful. But it does not cover encoding, escaping, or newline handling.

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

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

"Type literal text into whatever has focus" gives a specific verb (type), resource (literal text) and target (focused control), which an agent can act on immediately. It then explicitly distinguishes itself from app_set_dialog_control and app_send_keys, so the tool is identifiable among its UI-automation 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?

It states the when-not condition clearly: if the field has a handle, use app_set_dialog_control instead, because that addresses the control by name and reads the value back. It names the alternative and the condition that selects it, leaving nothing 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?

With no annotations at all, the description carries the full burden and does it well: 'Reads only. Takes no focus, moves no pointer, changes nothing, so it is safe while somebody is working' discloses side-effect profile, focus/pointer behavior and concurrency safety in one stroke. It further clarifies the read boundary (bar vs. contents) so the agent knows exactly what state is and isn't captured.

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 one-line summary, then a capitalized rationale and a safety note, so the important content is reached immediately. The 'four calls' anecdote is slightly long for the point it makes, but it justifies the tool's existence rather than padding.

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?

Zero parameters, an output schema present (so return shape needn't be described), and the description still covers scope, inclusion/exclusion of menu contents, and safety. Nothing an agent needs in order to decide to call it and interpret the result 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 confirms an empty properties object, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter-level gap exists.

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 in the first line: a full on-screen inventory of menus, panels, dialogs and toolbars in one call, and frames itself as the UI analogue of app_context. An agent can distinguish it from app_screenshot or app_read_window because the scope ('everything on screen') and the intent ('what am I looking at') are explicit.

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 when-to-use rationale: orientation at the start, replacing the four guessed calls that previously led callers to conclude a capability was missing. It also explains the inclusion boundary (menu bar listed, menu contents not) which implicitly routes content-opening tasks to the click/menu tools, but it never names an explicit alternative such as app_screenshot or app_list_panels.

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

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

No annotations exist, so the description carries the full burden and does so well: it discloses that the final step is irreversible and not undoable through this channel, that the script engine is blocked while the wizard is open, that no API exists, and that it halts on unrecognized dialogs. The one gap is that menu_may_steal_focus is never mentioned, so a focus-stealing side effect of the menu launch path goes undisclosed.

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?

Long (roughly 450 words) but front-loaded with a clear statement of the mechanism, then sectioned with capitalized headers (WHAT IT WILL DO AT THE END, WHAT IT CANNOT TELL YOU, LAUNCHING) that let an agent scan. Some redundancy between 'NOTHING IS SCRIPTED' and 'It STOPS rather than guessing' costs it the top score, but the length is justified by the irreversibility of the operation.

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?

An output schema exists, yet the description still adds useful return-value framing (ok, dry_run, committed, stopped_for_a_human, finished, steps with the WHY per dialog), which is more valuable than the bare schema. Combined with the mutation, launch, and failure-mode coverage, only the undocumented menu_may_steal_focus keeps it from being complete.

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

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

Schema coverage is 0% and the schema has no enums or per-field descriptions, so the description must compensate; it does for six of seven parameters, giving concrete values for target ('schematic'/'pcb') and launch ('already_open'/'menu') and explaining the consequence-named confirm_execute_eco and the timeout tuning. menu_may_steal_focus is left entirely undocumented.

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

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

States a specific verb and resource: it drives Altium's Tools > Update From Libraries wizard by pressing GUI buttons, through to executing the ECO. It distinguishes itself from the generic siblings (app_drive_dialogs, app_run_menu, app_press_dialog_button) by naming the exact Altium dialog and target variant, so an agent can tell what it does without opening the schema.

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

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

Explicit routing: dry_run defaults to true and the text says 'RUN IT DRY FIRST', launch defaults to already_open to avoid an unverified menu path, and it directs the agent to take app_checkpoint first and to read the Messages panel afterwards for the change list. It also states when it stops rather than proceeding, which is the key exclusion an agent needs.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses blocking behavior and the asynchronous race condition it addresses, but it does not explain timeout behavior, failure modes, or whether it matches an already-open dialog.

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

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

The first sentence is front-loaded and clear, and the following context explains the race condition efficiently. Some narrative phrasing, especially "the pattern this layer spent the day removing everywhere else," is less useful for an agent and could be tighter.

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

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

An output schema exists, so return values need not be explained. However, the tool has two undocumented parameters and no annotations, and the description omits timeout behavior and `title` semantics, leaving meaningful gaps 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?

The input schema has 0% description coverage for both `title` and `timeout`, and the description does not mention either parameter. It gives no guidance on whether `title` filters the awaited dialog or how `timeout` affects blocking behavior.

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

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

The description gives a specific verb and resource: "Block until a dialog appears, and report which one." That clearly identifies a wait-for-dialog operation, though it does not explicitly distinguish itself from siblings like app_list_open_dialogs.

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 the key usage context: a command that raises a dialog returns before the dialog exists, so acting and then looking can miss it. It also names fixed sleep as the inferior alternative, though it does not explicitly state when not to use this tool.

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

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

With no annotations, the description carries the full burden and does well: it discloses that both parameter slots and the on-canvas Comment field count, that IsHidden=True values do not satisfy the rule, and that it runs on the flattened tree so multichannel/hierarchical designs are covered. It stops short of stating explicitly that the tool is read-only and makes no design changes, which for an audit tool is the one remaining gap.

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

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

Front-loaded with the purpose sentence, then organized as scannable per-class bullets with the acceptance criterion embedded in each. The per-class rationale (overvoltage, core saturation, unprocurable footprint) earns its place, but the explicit 'Returns' block duplicates the output schema that already exists.

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 zero parameters and an output schema present, the description needs only to define what is checked and how — which it does thoroughly. The only shortfall is that, lacking annotations, it never explicitly declares the tool non-mutating, and it restates return fields already covered by the schema.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify and the baseline of 4 applies. Nothing in the text misleads about inputs.

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

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

The first sentence states a specific verb and resource: check that every placed component exposes the parameters its class requires, motivated by legible schematic and procurable BOM. The per-class rules make the scope unambiguous in practice, but the description never names the closely related siblings (audit_find_visible_supplier_pn, audit_find_placeholder_values, audit_find_mpn_inconsistencies) that an agent must disambiguate against.

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 through the stated goal (legible schematic, procurable BOM) and the note that it operates on the compiled/flattened tree, but there is no explicit 'use this when X, not when Y' statement and no mention of prerequisites such as needing a compiled project first. The agent must infer when this audit belongs in a review sequence.

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