BCD — Bridge Control Delegate

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

Adds substantial context beyond the annotations: the call returns the new app state with the next snapshotId (no extra snapshot required), stale-window calls are no-ops that return current state for retry, 'a sent action is not proof the task succeeded', and required ui/process permissions. This is rich behavioral disclosure for a non-read-only, non-destructive 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?

Purpose is front-loaded in the first sentence, and the remaining sentences carry real value (return shape, stale-state handling, verification caveat, permissions). Slightly dense for five sentences, but nothing 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?

With no output schema, the description usefully explains the return value and error/retry semantics, and covers permissions. Remaining gap is elementId semantics (valid range, how it maps to a snapshot element), which neither the schema nor the description fully supplies.

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

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

Schema coverage is 50% (deviceId and workSessionId documented, elementId and snapshotId bare). The description partly compensates by tying elementId to an element 'of the latest app_snapshot' and explaining that the returned snapshotId feeds the next call, but it adds no format or constraint detail for either 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: step an adjustable element (slider/stepper) down by one step, operating on the latest app_snapshot. The directional 'down' implicitly and cleanly separates it from the app_increment sibling without needing to name it.

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

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

Gives clear operating context (must act on the latest app_snapshot, needs ui and process permission) and recovery guidance when the window changed. It does not explicitly say when to prefer this over app_increment or app_select, so it stops just short of full routing 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?

Goes well beyond the annotations: it discloses the non-mutation guarantee ('without changing its text'), the return behavior (new state with next snapshotId, so no extra snapshot needed), the failure mode (window changed => no-op with current state returned for retry), a caveat that a sent action is not proof of success, and the required ui/process permissions. This is exactly the auth, side-effect, and failure-handling context annotations don't carry.

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

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

Purpose is front-loaded in the first clause, followed by return behavior, error handling, and permissions in short declarative sentences. The slogan-like line 'A sent action is not proof the task succeeded' is a touch cryptic, but overall there is little waste for the amount of behavior conveyed.

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

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

With no output schema, the description still explains the return value (new app state plus the next snapshotId), the error path (window changed, nothing done, state returned to retry from), and the permission prerequisites. Nothing an agent needs before calling this tool 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 only 50% (deviceId and workSessionId documented, elementId and snapshotId not), so the description has to compensate. It clarifies that elementId should point to a text field and that snapshotId refers to the latest app_snapshot, adding real meaning. It still leaves the elementId numbering scheme and snapshotId sourcing partially implicit, so not a full 5.

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

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

States a specific verb and target: 'Put the keyboard focus in a text field of the latest app_snapshot.' This is clearly distinguishable from siblings like app_type (which changes content) and app_press/app_select (which act rather than focus). The scope clause 'without changing its text' pins the intent precisely.

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

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

Gives clear operating context: it works on the latest app_snapshot, does nothing if the window changed, and requires ui and process permission. It does not explicitly name which sibling to use when you actually want to type, but 'without changing its text' implies the split with app_type, so guidance is present though not exhaustive.

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

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

Annotations only cover safety flags (not readOnly, not destructive, not openWorld), and the description adds substantial behavior beyond that: the return includes the new state and next snapshotId so no extra snapshot is needed, a changed window results in a no-op with the current state returned for retry, and a sent action is not proof of success. It also discloses the permission requirement.

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

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

Front-loads the action, then sequences return behavior, error handling, the success caveat, and permissions. Every sentence carries actionable information with no 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?

With no output schema, the description still explains the return value (new state plus next snapshotId) and the failure mode (error carrying current state to retry from). Combined with the permission note, an agent has everything needed to call and interpret 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 50% (deviceId and workSessionId are documented in the schema; elementId and snapshotId are not). The description implicitly explains snapshotId by tying it to the latest app_snapshot and elementId as an adjustable element, but adds no syntax or format detail, so it only partially compensates. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Step a slider, stepper or other adjustable element ... up by one step') that immediately separates it from the sibling app_decrement. An agent knows exactly what operation and target this performs 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?

Provides clear operating context: it acts on the latest app_snapshot, consumes a snapshotId, and requires ui and process permission. It does not explicitly contrast with app_decrement or spell out when-not to use it, so it falls short of full when/alternatives 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?

Adds rich traits beyond the annotations: a press can send, delete or quit; menu commands leave the front window as state; a window change means nothing is done and the error carries the current state; and 'a sent action is not proof the task succeeded'. It also discloses the required ui and process permissions and the risk that operating apps can run programs.

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

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

Front-loads the core purpose and keeps the high-value caveats (retry-on-window-change, permissions) tightly packed. It's dense but nearly every sentence earns its place; only the 'as in the app itself' clause is slightly 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?

Even without an output schema, the description explains the return value (the app's new state with the next snapshotId, so no extra snapshot is needed) and the error/retry contract. Combined with permissions and destructive-behavior notes, an agent has what it needs 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 only 50% (deviceId and workSessionId documented, elementId and snapshotId not). The description compensates by tying snapshotId to the 'latest app_snapshot' and clarifying that elementId is one of its elements, adding real meaning for the two undocumented parameters.

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 (press) plus the resource and scope (an element of the latest app_snapshot), and enumerates the concrete targets (button, menu item, link, checkbox). This lets an agent distinguish it from siblings like app_type, app_select, and app_increment without opening their schemas.

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

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

Clearly frames the precondition (must press an element of the latest app_snapshot) and the retry path when the window changes. It doesn't explicitly contrast when to use this over app_select/app_type, but the operating context is unambiguous.

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

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

Goes well beyond the annotations by disclosing that selecting usually opens an item, that the call returns the new state with the next snapshotId so no extra snapshot is needed, that a changed window causes a no-op with a retryable error carrying current state, and that a 'sent' action is not proof of success. It also states the ui and process permission requirement. This is rich behavioral context the structured fields do not carry.

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

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

Front-loads the core action and then layers behavioral details, with almost no filler. It is somewhat dense at five clauses, but each sentence carries distinct operational value rather than restating the name.

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

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

Despite having no output schema, the description explains the return value (the app's new state plus next snapshotId), the error/retry behavior, and the permission requirement. Nothing an agent needs to invoke this correctly appears to be missing.

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

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

Schema coverage is only 50% (elementId and snapshotId are undocumented in the schema), so the description should compensate more than it does. It implicitly maps 'row, tab or list item' to elementId and references the latest snapshot for snapshotId, but adds no format or constraint detail beyond that. Adequate but thin against the coverage gap.

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

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

States a specific verb (select) and resource (a row, tab, or list item of the latest app_snapshot), and adds the important effect that selecting a row usually opens it. An agent can distinguish this from siblings like app_press, app_snapshot, or browser_select without opening their schemas.

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

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

The description ties usage to 'the latest app_snapshot,' implying a snapshot must exist first, which is useful context. However, it never explicitly states when to prefer this over app_press, app_show_menu, or browser_select, nor any exclusion conditions, leaving the routing decision largely 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?

Goes well beyond the annotations: it describes the return behavior ('Returns the app's new state with the next snapshotId, so no extra snapshot is needed'), the failure mode ('If the window changed, nothing is done and the error comes with the current state to retry from'), a success caveat, and required permissions.

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 the follow-on sentences on return/error/permission behavior each carry real information. Dense 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?

With no output schema, the description does the heavy lifting by explaining the returned snapshot state, the retry-on-error path, and permissions. The main remaining gap is elementId semantics, which is left to the bare schema.

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

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

Schema coverage is 50%; deviceId and workSessionId are documented in the schema, while snapshotId and elementId are not. The description adds meaning for snapshotId ('latest app_snapshot', retry-from state) but says nothing about elementId beyond the schema, so it only partially compensates.

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

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

The description states a specific verb and resource ('Open the context menu of an element of the latest app_snapshot') and anchors it with a concrete analogy ('as a right-click does'). This distinguishes it clearly from siblings like app_press or app_select.

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 implies the workflow context (must operate on an element from the latest app_snapshot) but never states when to choose this over app_press, app_select, or app_increment. Usage is inferable but not explicit, with no exclusions.

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

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

Goes well past the readOnly/destructive annotations: snapshotId is valid for only one action, content outside the window's visible area is not listed, password fields render as (hidden), app text is untrusted content rather than instructions, and the call requires ui permission plus macOS Accessibility permission. These are exactly the behavioral traits an agent needs and cannot get from structured fields.

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

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

Front-loaded with the core purpose and the return shape, and every clause adds real information (scope, ids, snapshotId lifetime, permissions). It is delivered as one dense multi-clause block rather than separated points, which slightly hurts scanability, but there is little outright 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?

No output schema exists, yet the description describes the return shape, its limits (visible area only), and the permission prerequisites, so an agent can call it correctly. The remaining gap is operational: truncation via maxElements and the meaning of the window index are never addressed.

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

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

Schema description coverage is only 29%, so the description must carry the load. It explains 'app' (name or bundle id, omit for front), 'menu' (one menu name includes its submenus), and implies 'scope', but says nothing about 'window' (which window index), 'maxElements' (truncation behaviour), 'deviceId', or 'workSessionId'. Partial compensation for a low-coverage 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 ('Read a native Mac app as a screen reader does') and enumerates exactly what is returned: controls, text, ids, roles, names, values, operations, and a snapshotId. It also distinguishes itself from the sibling action tools by naming the operations (press, type, select...) as the app_ tools that consume this snapshot.

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 operating context: omit 'app' for the front app, use scope=menus to walk the menu bar, name one menu to include its submenus, and that it works on non-front apps listed by runningApps. It stops short of explicitly saying 'call this first to obtain the snapshotId before any app_press/app_type', which is only implied by 'valid for one action'.

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

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

Goes well beyond the annotations by disclosing that the call returns the app's new state with the next snapshotId (no extra snapshot needed), that a changed window aborts the action and returns the current state to retry from, that a sent action does not prove success, and that ui/process permission is required. The destructiveHint annotation is matched by the explicit 'replace the text' wording rather than contradicted.

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 layers prerequisites, return semantics, and failure behavior. Dense and slightly telegraphic in places ('A sent action is not proof the task succeeded'), but nearly every sentence adds information an agent needs.

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

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

With no output schema, the description does the work of explaining the return value and the error-with-state recovery path, and it lists required permissions. The main gap is the undocumented elementId parameter, but overall the picture is complete enough to invoke 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 only 40% across five parameters. The description meaningfully constrains snapshotId to the latest app_snapshot and implies a UI element target, and deviceId/workSessionId carry their own schema descriptions, but elementId and the text length bound are left entirely to the schema.

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

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

The description opens with a specific verb and resource: replacing the text of a text field on the latest app_snapshot, with an explicit scope limit (never a password field). It is clearly distinguishable from siblings like app_press or app_select, though it does not explicitly contrast itself with the similarly named browser_type.

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 real operational context: the field must belong to the latest snapshot, apps that don't register typing as an edit require an explicit save, and ui/process permission is needed. It stops short of naming alternatives or stating exclusions beyond the password-field restriction.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description goes well beyond that: it specifies that no further step starts, that a running command is stopped while a running file step or copy completes first, and that completed steps are not rolled back. This granular cancellation semantics and irreversibility disclosure is exactly the extra context annotations cannot carry.

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

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

Four short sentences, front-loaded with the action and target, then the behavioral caveats, then the follow-up instruction. No filler and every sentence carries decision-relevant 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?

No output schema exists, so the description must cover outcomes — and it does via the 'poll workflow_status until cancelled' instruction, plus the per-step cancellation behavior. It omits edge cases such as what happens if the run has already finished or failed, which keeps it short of fully 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 67%: deviceId and workSessionId are already documented in the schema, while runId has no schema description. The description only says 'by runId' and 'in the same work session', which adds minimal meaning beyond what the schema properties already convey. Baseline 3 is appropriate when the schema does most of the work.

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

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

Specific verb (cancel) plus resource (workflow run) plus identifier (runId) and session scoping ('in the same work session'). An agent can immediately separate this from siblings like delete_workflow (definition removal), run_workflow, or workflow_status.

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

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

Gives clear context for use (a running workflow run) and names the follow-up action to take — 'Poll workflow_status until the state is cancelled' — which routes the agent to the correct next tool. It does not, however, state when not to use it (e.g. vs delete_workflow for a non-running workflow), so exclusions are left implicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the meaningful context that the operation id comes from an unknown-outcome error, but it never states what the check actually returns (ran / did not run / still running), which is the key behavioral detail for deciding whether to retry.

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

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

Two tight sentences, front-loaded with what the tool does and immediately followed by the when-to-use trigger. Zero filler and no repetition of the name or annotations.

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

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

With no output schema, the description bears more of the burden for explaining results, yet it never says what a positive or negative check means for the retry decision. Purpose and invocation are well covered, but the outcome interpretation is left implicit for a tool whose whole value is resolving an ambiguous outcome.

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

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

Schema coverage is 67%; deviceId and workSessionId are documented in the schema, while operationId carries only a pattern. The description compensates for that gap by explaining where the operationId comes from (an unknown-outcome error), adding real meaning beyond the schema for the one required 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 (check) and resource (operation) plus the mechanism: verifying whether an earlier call ran on this computer, keyed by an operation id from an unknown-outcome error. It is clearly distinct from sibling tools like get_work_session or list_process_sessions, though it does not name a sibling to differentiate itself explicitly.

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

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

Gives a concrete trigger condition: 'Use it before retrying a call whose outcome is unknown.' This tells the agent exactly when to reach for it. It stops short of naming alternative tools or stating when not to use it, so it is clear context without exclusions.

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

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

Adds substantial behavior beyond the annotations: never overwrites or merges an existing destination, does not follow symlinks, caps at 2 GB/10000 entries, returns a copyId immediately, and warns that an interrupted copy may leave a partial destination to inspect before retrying. That is exactly the kind of operational context annotations cannot express.

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

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

Front-loads the core action and its safety profile, then layers limits, return behavior, and failure recovery in compact sentences. No sentence is redundant and nothing is buried.

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

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

With no output schema, the description supplies the return contract (copyId plus polling via copy_status) and covers limits, symlink handling, and interrupted-copy recovery. Nothing an agent needs to invoke and follow up on this tool correctly is missing.

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

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

Schema coverage is 50% and from/to carry no schema descriptions, so the description does real work by clarifying the source/destination relationship and the non-overwrite rule. It reinforces workSessionId usage for polling, though it says nothing about deviceId, leaving one parameter unaddressed.

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

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

States a specific verb and resource ('Copy a file or directory') plus the key scope qualifier 'keeping the source intact', which cleanly separates it from move_path. An agent can distinguish it from siblings 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?

Explicitly routes the agent to copy_status with the same workSessionId for progress, and the 'source intact' phrasing implies when to prefer this over move_path. It does not state outright when-not-to-use or name move_path as the alternative, so it falls just short of a 5.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=false. The description adds genuinely non-structured behavior: the source is never removed, and failed or interrupted jobs are never replayed automatically — important expectations for an agent polling a job.

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

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

Three tight sentences, front-loaded with the purpose, then the usage constraint, then behavioral caveats. No filler; every clause carries information.

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

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

With no output schema, the description does name what is returned (progress, outcome, undo changeId), and annotations cover the safety profile. It could say more about polling cadence or terminal states, but nothing essential to correct invocation is missing.

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

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

Schema coverage is 67% and the schema already documents deviceId and workSessionId including the 'same ID on every call' guidance. The description only reinforces the workSessionId intent and says nothing about copyId, the sole required parameter, so it adds marginal 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?

States a specific verb ('Read') and resource ('an explicit copy job'), and enumerates what it surfaces: progress, outcome, and undo changeId. This clearly separates it from generic status siblings like check_operation or workflow_status.

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

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

Gives a concrete usage condition — 'Use the original workSessionId' — implying it is called after a copy job is started to poll its state. It stops short of naming alternative tools or stating when not to use it, but the context is clear.

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

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

Annotations only declare it is not read-only, not destructive, and not open-world. The description goes well beyond that: lifecycle ('Sessions unused for 30 days, or the least recently used past 500, are forgotten; their folders stay') and path-resolution semantics ('Relative file paths and commands without cwd use that workspace; ~ still means home'). These are exactly the behavioral details an agent cannot infer from the annotations.

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

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

Front-loaded with the action and its product, then moves through retention, path semantics, and scope in tight sentences with no filler. Dense but every clause carries information; slightly long, though nothing is redundant.

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

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

For a creation tool with no output schema and only four parameters, the description covers the essential unknowns: what is created, the retention rule, path resolution, and what the session does not control. The remaining gap is the meaning/format of name and workspaceRoot, which neither schema nor description fully addresses.

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

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

Schema coverage is 50%: deviceId and workSessionId are self-documented, while name and workspaceRoot are not. The description adds real meaning for workspaceRoot by explaining relative-path and cwd resolution, plus the role of the returned workSessionId. However, it never explains name or workspaceRoot's own format, so it does not fully compensate for the coverage gap.

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

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

States a specific verb and resource ('Create a separate work session ... and a unique workspace folder') and immediately scopes it to 'this AI conversation', which distinguishes it from get_work_session and list_work_sessions. An agent can tell what it produces and why without opening a schema.

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

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

Gives explicit operational guidance: 'Keep the returned workSessionId and pass it on every subsequent call, including process output and undo.' It also clarifies what this session does and does not govern ('separates activity and process control, not access to shared absolute paths or the physical browser'). It stops short of naming sibling alternatives explicitly, but the when-to-use condition is unambiguous.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful extent-of-destruction detail: the saved workflow persists and an in-flight run completes — context the annotations cannot express and that materially affects an agent's decision to call 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?

Two short sentences, front-loaded with the action and identifier, then the consequences. No filler and nothing that could be dropped 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?

For a one-parameter destructive tool with annotations covering the safety profile and no output schema, the description supplies the key behavioral caveats. It is slightly thin on idempotency and how to source the scheduleId, but nothing critical 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% for the single parameter, so the description carries the burden; it names scheduleId and identifies it as the schedule reference, which is more than the bare uuid schema. However it does not say where to obtain a valid scheduleId (e.g., list_scheduled_workflows) or address behavior for unknown IDs.

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 ('Stop') and resource ('scheduled workflow') and is scoped by an explicit identifier. It implicitly distinguishes itself from the sibling delete_workflow by clarifying that the saved workflow itself remains, though it never names that sibling explicitly.

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

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

The description conveys scope (what is not affected) but offers no explicit when-to-use guidance and does not contrast itself with adjacent tools such as cancel_workflow or delete_workflow. Usage is inferable from the effect statements rather than stated.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuine value beyond that by clarifying what is NOT destroyed (run records and output files remain), which is exactly the kind of scope-of-destruction context an agent needs before a delete.

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

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

Two short sentences, zero filler, with the destructive scope stated first and the non-destructive consequence second. Fully front-loaded.

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

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

For a destructive delete with no output schema and mostly-covered params, the description conveys what is destroyed and what survives, which is the essential missing piece. It omits error/permission behavior but nothing an agent critically needs to invoke it correctly.

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

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

Schema coverage is 67%: deviceId and workSessionId are documented in the schema, while workflowId has no schema description. The description names workflowId as the deletion key and frames it as the caller's own definition, adding marginal meaning, but does not compensate for the undocumented workflowId semantics.

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

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

States a specific verb (Delete) and a precisely scoped resource ('this caller's saved definition by workflowId'), and clarifies that run records/outputs are unaffected, which separates it from a run-cancellation tool. It doesn't explicitly name a sibling to contrast with, so it falls short of 5.

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

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

Usage is implied by the scope (delete the saved definition), but there is no explicit when-to-use, when-not-to-use, or routing to alternatives such as cancel_workflow or remove_path for stopping runs or clearing files. Adequate minimum, no exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered; the description still adds real value by disclosing the 90-second cap and the partial-result contract ('complete: false with the items finished by then'), and by clarifying the measurement semantics (allocated space, as du counts it). It does not mention behavior on unreadable or permission-protected folders, which is a minor remaining gap.

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

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

Three sentences, each earning its place: the first defines the operation and output, the second the drill-down pattern, the third the timeout edge case. The scoping ('without changing anything') is front-loaded and there is no filler.

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

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

With no output schema, the description carries the return-value burden and does so reasonably: ranked items, item sizes, folder total, and a completion flag. It is essentially complete for a 4-parameter read-only tool, though it leaves the per-item fields (e.g., name vs path) unspecified.

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

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

Schema description coverage is 100%, so path, limit, deviceId, and workSessionId are already documented in the schema; the description adds only a loose implication of the path parameter ('in a folder', 'call it again on a large item'). Baseline 3 is appropriate when the schema does the heavy lifting and the description adds nothing parameter-specific.

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 ('Show what takes up disk space in a folder') plus the exact return shape: size of each item directly inside, largest first, and the folder total. This clearly separates it from siblings like list_directory, stat_path, and search_files, which enumerate or inspect paths but do not rank by disk consumption.

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

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

Gives a concrete usage pattern: 'Call it again on a large item to look inside,' which tells the agent to drill down iteratively rather than expecting recursion. However, it names no alternative sibling (e.g., list_directory or stat_path) nor any condition under which this tool should not be used, so it stops short of full routing guidance.

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

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

Annotations already establish destructive=true and readOnly=false, but the description adds genuinely new behavior: the operation is atomic on mismatch ('nothing changes') and returns the closest match as feedback. Permission/session requirements for deviceId and workSessionId are left to the schema rather than the description.

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 replace semantics come first, then format-specific variants, then the failure behavior. Every clause is load-bearing with no filler.

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

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

For an 8-parameter mutation tool with no output schema, the description covers the fallback behavior, format branches, and matching rules. Remaining gaps (device/work session scoping) are handled by schema descriptions, so an agent has enough to invoke it correctly.

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

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

Schema coverage is only 25% (two of eight params documented), so the description has to carry the load and largely does: it explains old_string/new_string semantics, the expected_replacements default of 1 and the uniqueness requirement, plus range and content formats. Only file_path and the session/device params are not elaborated 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?

Names a specific verb and resource ('Edit a file in place') and states the exact mechanism ('replaces old_string with new_string ... exactly expected_replacements times'). It also carves out sibling territory by naming edit_docx for the cross-formatting case.

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 conditions for the spreadsheet case (range plus a 2D content array) and the DOCX case, and routes the cross-formatting scenario to edit_docx. It does not clarify how this differs from edit_spreadsheet, which remains a live alternative for the range/content path.

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

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

Annotations declare non-destructive (destructiveHint=false, readOnlyHint=false), and the description adds rich context beyond them: the original is kept because a new outputPath is written, images/fields/untouched parts are preserved, and signed files are refused. This is exactly the extra behavioral disclosure annotations cannot supply.

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

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

Dense and front-loaded: the core action leads, then output behavior, occurrence rule, part/mode options, and preservation/refusal caveats follow. Slightly run-on but every clause carries information.

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

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

With 10 parameters, low schema coverage and no output schema, the description covers the essential behavior, defaults and edge cases (signed-file refusal, preservation) but never states what the call returns. That omission is the main remaining gap.

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

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

Schema coverage is only 20%, so the description must compensate. It explains oldText occurrence semantics, the part values (body default, header, footer, all) and mode xml, but leaves newText, inputPath and includeHeadersFooters undocumented in both schema and description, so compensation is partial.

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 ('Replace exact text in a Word .docx') and adds the distinguishing scope detail 'even where it spans formatting runs', which separates it from generic write_file/edit_block siblings. An agent can identify the operation 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?

Provides concrete when-to-use conditions: mode xml requires XML copied from read_file with docxMode xml, and oldText must occur expectedOccurrences times. It gives clear context but does not explicitly rule out alternatives or state when-not to use 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?

Annotations declare readOnlyHint=false, destructiveHint=false, openWorldHint=false. The description adds significant behavioral context: it writes to a new outputPath, keeps the original, preserves styles/charts/images/merged cells/tables/VBA (never run), recalculates formulas, and reports what was preserved. This goes well beyond the annotations and is exactly what an agent needs for a mutation tool.

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

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

The description is a single, dense, front-loaded sentence plus one short follow-up. Every phrase adds value: file types, edit types, output behavior, preservation guarantees, formula handling, and sibling routing. No waste.

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

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

For a mutation tool with annotations and a complex nested schema, the description covers the key behaviors: output file creation, preservation of features, formula recalculation, VBA safety, and report. It does not describe the edits structure (cell/range/rows/values/sheetName/sheetIndex), which is a gap given 40% schema coverage, but the essential behavioral context is present.

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

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

Schema coverage is 40% (only deviceId and workSessionId have descriptions; inputPath, outputPath, edits lack descriptions). The description mentions inputPath/outputPath implicitly via 'into a new outputPath' and 'keeping the original', but does not describe the edits schema at all. Since schema coverage is low, the description should compensate more, but it does convey the core semantics of input/output 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?

The description states a specific verb+resource: 'Edit cells or ranges, or append rows, in an Excel workbook (xlsx, xlsm, xls) into a new outputPath'. It also references the sibling 'edit_block' and distinguishes the two by when to use each. This is a clear, actionable purpose statement.

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 guidance: 'Use it when edit_block refuses an in-place edit.' This directly tells the agent the condition under which to choose this tool over the alternative, with no ambiguity.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safe-read profile is fully covered without the description. The description adds the retrieval scope ("steps and parameters") but says nothing about return format, size, or any behavioral trait beyond the annotations.

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

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

A single front-loaded sentence with zero filler; the core action is stated before the usage hint. Every word earns its place.

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

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

With no output schema, the description loosely signals the return ("exact steps and parameters"), which is helpful, but it leaves the workflowId parameter undocumented and does not route the agent against siblings like list_workflows or workflow_status. Adequate but with clear gaps for a 3-param getter.

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

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

Schema coverage is 67%, with deviceId and workSessionId documented in-schema, and the required workflowId (self-evidently the workflow to fetch) left undocumented. The description adds no parameter meaning at all, so it neither compensates for the gap nor exceeds the schema baseline.

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 ("Review the exact steps and parameters of a saved workflow") that clearly identifies retrieval of a stored workflow definition. It does not, however, distinguish itself from nearby siblings like list_workflows or workflow_status, leaving the agent to infer the difference.

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

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

The phrase "before rerunning it" implies a usage context (pre-flight inspection prior to run_workflow), which is useful but only implied. There is no explicit when/when-not guidance or named alternative such as workflow_status for live execution state.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered without the description. The description adds useful context about what is shown and the conversation-scoping boundary, but says nothing about freshness, result size, or what happens for legacy unscoped sessions.

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

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

Two tight sentences with no filler, and the core purpose is front-loaded ahead of the scoping constraint and the ID requirement. Efficient, though the 'Requires workSessionId' clause is arguably incorrect rather than merely redundant.

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

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

For a read-only status tool with no output schema, the description adequately conveys what is returned (workspace, active tool calls, recent runs) and the conversation scoping. It falls short only on timing/freshness and on reconciling the required-vs-optional conflict for workSessionId.

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

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

Schema coverage is 100%, so both parameters are already fully documented, establishing the baseline of 3. The description's 'Requires workSessionId' adds little and is actually slightly at odds with the schema, where workSessionId is not required and may be omitted for legacy unscoped work.

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 (Show) and names the exact resource and contents: the selected conversation's workspace, active tool calls, and recent workflow runs. This differentiates it from create_work_session, list_work_sessions, and workflow_status, though it never names those siblings explicitly.

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

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

The scope clause ('other conversations' activity is excluded') and the 'Requires workSessionId' note imply when this tool applies, but there is no explicit when-to-use or when-to-prefer-an-alternative guidance (e.g. vs. list_work_sessions or workflow_status). Usage must be inferred.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, which fit an archiving write, so no contradiction. The description adds behavior annotations do not carry: it runs as a background job, returns a jobId, requires polling via ios_build_status, performs signing with project settings, and uploads nothing. It does not say whether an existing .xcarchive is overwritten or how long the job typically takes.

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

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

Three short sentences, zero waste, front-loaded with the core action and immediately followed by the key exclusion and the required follow-up. Every sentence earns its place.

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

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

For a 9-parameter async mutation with no output schema, the description supplies the critical missing pieces: async job semantics, the jobId return, the polling tool, and the no-upload scope. Remaining gaps (overwrite behavior, success/failure reporting) are minor given annotations cover the safety profile.

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

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

Schema description coverage is 78%, so the schema already documents most parameters including keyId, teamId, project, deviceId, and buildNumber. The description only alludes to signing settings generally and adds no syntax or format detail beyond the schema, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb (Archive) and resource (a scheme for devices -> .xcarchive) plus the locality (on this Mac) and signing basis. It also names the sibling it is not, ios_testflight, so the agent can separate archival-only from archive-and-upload 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 routing: 'Nothing is uploaded; ios_testflight archives and uploads' tells the agent which tool to pick and why. It additionally instructs the caller to poll ios_build_status with the returned jobId, covering the follow-up step after invocation.

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

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

Annotations mark it non-read-only, closed-world, and non-destructive, and the description adds genuinely useful behavior beyond those: it runs as a background job, returns a jobId, must be polled via ios_build_status, and uploads nothing. It could say more about failure output or build artifacts, but the async contract is well disclosed.

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

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

Three tight sentences, front-loaded with the core action, then the async lifecycle, then the safety note. No padding or restatement of the name.

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

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

With no output schema, the description correctly supplies the return contract (jobId) and the follow-up tool, which is the key missing piece. It is complete for invocation, though it leaves configuration/scheme semantics to the schema.

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

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

Schema coverage is 75% and the schema already documents project, deviceId, teamId, destination, buildNumber, and workSessionId. The description's "for the iOS Simulator unless destination says otherwise" largely restates the destination default already in the schema, so it adds little beyond the baseline.

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 ("Build a scheme of an Xcode project") plus the goal (check that it compiles) and the environment (this Mac, iOS Simulator by default). An agent can distinguish it from ios_test, ios_archive, and ios_build_status without opening any schema.

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

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

Gives clear context: use it to verify compilation, and it routes the agent to ios_build_status for polling the background job. It does not explicitly contrast with alternatives like ios_test or ios_archive, so the when-not is left implicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds one behavioral detail (fallback to listing recent jobs when jobId is absent), but says nothing about polling, pagination of the recent-jobs list, or auth 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?

Two sentences, front-loaded with the core action and its returned fields, then the fallback behavior. The field enumeration is dense but earns its place given there is no output schema.

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

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

With no output schema, the description carries the return-value burden and does so well by listing state values, phase, compiler errors, failing tests, TestFlight outcome, and log tail. It is nearly complete, lacking only guidance on the deviceId/workSessionId context that the schema partially covers.

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

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

Schema coverage is 75%; waitMs, deviceId, and workSessionId are documented in the schema, but jobId has no schema description. The description compensates by establishing that jobId is optional and what happens without it, adding real meaning for the one undocumented 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 (summarize) and resource (iOS job/build) and enumerates the exact contents of the summary. It is clearly distinguishable from the sibling ios_build, which starts a build rather than reporting on one.

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 one useful usage rule: 'Without a jobId, list recent jobs,' which tells the agent how the tool behaves with and without the key parameter. However, it names no alternative tool (e.g., ios_build, job listing) and no conditions for when not to use 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?

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: the tool has two modes (enumerate all projects vs. list schemes for one) and is a read-only discovery entry point. It doesn't mention rate limits or output shape, but against existing annotations this is above baseline.

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

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

Two sentences, zero filler, and the primary discovery behavior is front-loaded ahead of the workflow-ordering cue. Every clause earns its place.

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

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

For a 0-required-parameter, read-only discovery tool with full schema coverage and no output schema, the description covers purpose, two operation modes, and sequencing. It could say more about what a no-argument call returns, but nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters in detail (project path, deviceId source, directory, workSessionId). The description mentions the 'one of them' listing behavior that corresponds to the project param but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Find the Xcode projects and workspaces on this Mac') and clarifies the second mode of operation ('for one of them, list its schemes and build configurations'). It explicitly names the sibling tools it precedes, so an agent can distinguish it from ios_build/ios_test without opening any schema.

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

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

'Start here before ios_build, ios_test, ios_archive or ios_testflight' gives explicit ordering guidance and names all four alternative tools. The agent knows exactly when to reach for this tool rather than a downstream build/test tool.

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

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

Annotations already declare readOnly=false, destructive=false, openWorld=false, but the description adds genuinely new behavior: asynchronous execution, a returned jobId, the required polling step, and that the status lists failing tests. That is real context beyond the annotations, though permission/auth requirements are not mentioned.

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

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

Three short sentences, each earning its place: what it does, the async job contract, and the polling target. The async nature of the operation is front-loaded immediately after the purpose.

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

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

With no output schema, the description correctly compensates by explaining the return value (jobId) and the follow-up status call that reports failing tests. It is essentially complete for invocation, missing only device/destination defaults that the schema partially covers.

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

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

Schema coverage is 67%, so most parameters are documented in the schema. The description implies the 'scheme' and simulator/device selection but adds no syntax or default guidance for parameters like destination, configuration, or workSessionId. Baseline 3 is appropriate given the moderately self-documenting 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 ('Run a scheme's tests on an iPhone simulator on this Mac') and clearly distinguishes itself from sibling ios_build by describing the test-run job model. An agent can tell what this 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?

Explicitly tells the agent this runs as a background job, returns a jobId, and that the agent must poll ios_build_status with that id. This is clear operating context, though it does not explicitly contrast when to use this versus ios_build or ios_archive.

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

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

Annotations declare destructiveHint=true and openWorldHint=true, and the description goes well beyond them: the upload is irreversible, the build number is consumed, user confirmation is required, credentials live in ~/.appstoreconnect and the issuer is remembered after first use, and the call runs asynchronously returning a jobId. This is exactly the behavioral context annotations cannot convey.

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

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

Four tightly packed sentences, front-loaded with the action, then the irreversible side effect, then the default, then the async return contract. No filler and no repetition of schema 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?

For a 9-parameter destructive async tool with no output schema, the description covers the irreversibility, the credential model, the buildNumber default, the user-confirmation requirement, and the return/polling contract. Nothing an agent needs to invoke it 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?

Schema coverage is 78%, so the baseline is 3, but the description adds real meaning: buildNumber defaults to a UTC timestamp so each upload is unique (the schema only says it sets CURRENT_PROJECT_VERSION), and it explains that issuerId is persisted after the first upload. Two parameters (configuration, workSessionId) get no description-level elaboration, which keeps this from a 5.

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 precise compound action — archive a scheme then upload to App Store Connect for TestFlight — which cleanly separates it from ios_archive, ios_build, ios_test and ios_build_status. The verb+resource+destination are all explicit, so an agent can route to it 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 a concrete prerequisite behavior ('confirm with the user first') and routes the agent to the follow-up sibling ('poll ios_build_status with it'). It also explains when to rely on the default buildNumber. It stops short of an explicit when-to-use-this-vs-ios_archive rule, so it is strong but not fully prescriptive.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds the account scope and, with no output schema present, discloses what the response contains (names, permissions, which device is default), which is genuine added context.

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

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

Two tight sentences, front-loaded with the primary action and followed by the downstream hint. No filler, no repetition of the title, every clause carries information.

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

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

For a zero-parameter, read-only discovery tool with no output schema, the description is essentially complete: it says what is listed and what fields come back. Only minor detail (ordering or whether multiple accounts/devices can appear) 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?

The tool takes zero parameters, so the baseline of 4 applies. The description correctly notes that the ids it surfaces are meant to be passed as 'deviceId' to other tools, tying the output to downstream parameter usage.

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 computers currently connected to your BCD account') and even enumerates the returned fields (names, permissions, default flag). It is unambiguous, though it does not need to distinguish itself from any sibling since no other device-listing tool exists.

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 closing sentence 'Pass a name or id as deviceId to other tools' gives real workflow context: it tells the agent this is a discovery step whose output feeds downstream calls. It stops short of an explicit when-not-to-use or naming a specific alternative tool.

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

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

Annotations already declare this is a safe, read-only, non-destructive, non-open-world operation, so the bar is lower. The description still adds real behavioral value by disclosing the depth-first output ordering and the per-subfolder cap of 100 entries, which an agent cannot infer from annotations or schema.

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

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

Two compact sentences with zero filler; the output format is stated first and the depth semantics follow, so the most decision-relevant information is front-loaded.

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

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

With no output schema, the description usefully covers the return format and the 100-entry truncation, which is the main completeness risk. Minor gaps remain on the path default and on what depths 0 and 3-5 actually do.

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

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

Schema description coverage is only 50% (path and depth are undocumented in the schema), yet the description fully explains depth: default 2, depth 1 meaning, and recursion semantics. The path parameter's "~" default and depth values 0 or 3-5 remain unexplained, so it stops short of a 5.

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 ("a folder") and even pins down the output line format with [DIR]/[FILE] prefixes. It does not explicitly differentiate itself from siblings like search_files or stat_path, which keeps it just 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 depth explanation gives implicit guidance on how to scope a listing (shallow vs. recursive), but there is no explicit when-to-use/when-not-to-use statement or pointer to an alternative such as search_files for content-based discovery.

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

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

Annotations already declare readOnlyHint and destructiveHint=false, yet the description adds substantial behavioral context: retention bounds (100 changes/250 MB/30 days per caller, oldest dropped first), which change types are tracked (writes, edits, moves, explicit copies), and which are not undoable (shell commands, deletes, untracked/oversized). This is real value beyond the structured fields.

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

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

Front-loaded with purpose, then dense, non-redundant sentences covering ordering, change types, retention bounds, and undo exclusions. Every clause carries information an agent needs; nothing 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?

With no output schema present, the description responsibly states the notable return fields (changeId, undo availability) and ordering. Minor gaps remain around pagination/limit interplay, but coverage is strong for a read-only list tool.

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

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

Schema coverage is 67%; deviceId and workSessionId are documented in the schema itself, while limit is undocumented. The description's 'bounded to 100 changes' loosely relates to limit's maximum of 100 but adds no per-parameter guidance, so this sits at the baseline where the schema does most of the work.

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 (retained file changes in this work session) with scope and ordering, and cites the key output fields (changeId, undo availability). An agent can distinguish it from the write/mutation siblings like write_file or undo_file_change immediately.

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

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

The description implies when to reach for it (checking what changed before undoing), but never explicitly names undo_file_change as the alternative or states when-not to use it. Usage is inferable rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds useful content context – results are bounded metadata and command arguments are withheld – but says nothing about pagination behavior, result size, or platform/permission requirements.

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

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

Two short sentences, zero filler, with the primary purpose front-loaded and the output caveat placed second. Nothing here wastes the agent's attention.

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

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

With no output schema, the description partly compensates by disclosing that returned metadata is bounded and excludes command arguments. However, for a 4-parameter tool it leaves pid/limit semantics and the relationship to list_process_sessions unexplained, so it is only minimally adequate.

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

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

Schema coverage is only 50%: pid and limit have no descriptions at all, and the description never mentions them, so their semantics (single-process lookup vs. result cap) remain undocumented. The word 'bounded' hints at a limit but adds no actionable detail, leaving the description unable to compensate for the coverage gap.

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

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

Clear specific verb+resource: 'List bounded process metadata' scoped to 'processes owned by the current user', plus a stated output limitation ('Command arguments are omitted'). It does not, however, distinguish itself from the nearby sibling list_process_sessions, leaving the agent to infer which process-listing tool applies.

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

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

No when-to-use, when-not-to-use, or alternative guidance is given. The scope constraint ('owned by the current user') is a filter, not guidance about selecting this tool over list_process_sessions or system_info.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description nonetheless adds real behavioral context beyond them: results are ordered newest-first and include sessions from earlier connections, which tells the agent that history persists across reconnects.

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

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

A single tight sentence with the verb and scope front-loaded and the returned fields trailing. Dense but every clause carries information; it could be slightly easier to parse if split, but there is no waste.

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

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

With no output schema, the description usefully enumerates the returned fields (id, status, exit code, waiting-for-input) and the ordering, which is what an agent needs to consume the result. The remaining gap is the unspecified limit behavior (default 100, max 500) and how deviceId/workSessionId narrow the list.

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 67%, with deviceId and workSessionId documented in-schema and limit carrying only default/min/max constraints. The description adds no parameter-level meaning (no mention of pagination, limit semantics, or how deviceId/workSessionId filter the list), so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('List start_process sessions') and immediately defines scope (newest first, including sessions from earlier connections) plus the returned fields. An agent can distinguish this from siblings like list_work_sessions or list_devices without opening any schema.

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

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

The description implies the tool's role as the listing counterpart to start_process, and the 'including ones from earlier connections' clause hints at a retrieval scope, but it never states when to use this versus alternatives such as list_work_sessions or process_output, nor any exclusion conditions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds value beyond annotations by disclosing the shape of the result set (computer, workflow, run time, next run, last run outcome) despite there being no output 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?

One front-loaded sentence with a colon-delimited list; every clause conveys new information about what the listing contains. It is appropriately sized, though the trailing enumeration is slightly dense.

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

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

With no output schema, the description correctly carries the burden of describing return content, and the single optional parameter is fully specified in the schema. It omits minor operational details such as ordering, limits, or whether paused schedules are included.

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

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

Schema description coverage is 100% and the single optional deviceId parameter is already documented, including its optionality and the reference to list_devices. The description adds no additional parameter meaning, so the baseline 3 applies.

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

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

States a specific verb (List) and a precise resource scope (this account's scheduled workflows), and even enumerates the record fields returned. It does not explicitly differentiate itself from siblings like list_workflows, get_workflow, or workflow_status, 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 says what is listed but never when to reach for this tool versus list_workflows, get_workflow, or workflow_status, and gives no prerequisites or exclusions. The only routing hint ('from list_devices') lives in the schema, not the description.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds useful durability context ('definitions survive reconnects and restarts') but says nothing about pagination or return shape.

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

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

Two tight sentences with the core purpose front-loaded and the persistence note secondary. No wasted 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?

No output schema exists, and the description does hint at returned content ('including input names'). However, it omits pagination/limit behavior for what is clearly a list operation, leaving a gap for a read tool with an undocumented limit parameter.

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

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

Schema coverage is 67%, and the 'limit' parameter has no description in either the schema or the description. The mention of 'saved on this computer' loosely relates to deviceId but adds no syntax, defaults, or coupling guidance beyond the schema.

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

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

States a specific verb (List) plus resource (reusable workflows) with clear scope: 'this caller's ... saved on this computer.' This distinguishes it from get_workflow (singular) and save/delete/run_workflow, though it never names those siblings explicitly.

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

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

Provides no when-to-use/when-not guidance and names no alternatives. It doesn't say to use get_workflow for a single workflow or explain the deviceId/workSessionId omission choices, leaving routing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and a closed world, so the safety profile is covered. The description adds only the caller-scoping and post-reconnect resumption context; it says nothing about pagination behavior, result ordering, or what happens when no sessions exist, so it adds modest value over the structured fields.

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

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

A single front-loaded sentence that leads with the action and resource, with the motivating context trailing. There is no filler, though it is terse enough that it omits guidance rather than being 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 read-only list tool with annotations carrying the safety profile and no output schema, the description covers the essential 'what and why'. It remains incomplete regarding pagination (a limit param exists with no explanation) and how it relates to the get_work_session / create_work_session 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?

Schema coverage is 67%: deviceId and workSessionId are documented in the schema, while limit is not. The description reinforces the workSessionId use case ('resume with its workSessionId'), but adds no format, range, or behavior detail beyond the schema, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('List this caller's work sessions') with explicit scope ('on this computer'), so an agent knows exactly what it does. It does not, however, differentiate itself from the sibling get_work_session or list_process_sessions, leaving the reader to infer the boundary from names 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?

It implies a usage context - resuming a conversation after reconnecting by retrieving its workSessionId - which gives the agent a reason to call it. But it never states when to prefer this over the sibling get_work_session, nor any prerequisite (e.g., needing a device online), so exclusions and alternatives are absent.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, and the description adds real behavioral context beyond them: it creates missing parents recursively and does not error on an existing folder. It stops short of stating permission needs, path-format expectations, or what happens when the path collides with a file.

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

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

Two short sentences, zero filler, with the core action front-loaded. Nothing is wasted and both sentences carry 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 simple 3-param tool with no output schema, this is adequate: the target device/session params are covered in the schema and no return value needs explaining. However, the undocumented required path parameter and absent usage context leave it minimal rather than 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 67%: deviceId and workSessionId are documented, but the required 'path' param has no schema description at all. The description only says 'Create a folder' and does not clarify whether path is absolute/relative or its format, so it fails to compensate for the path gap.

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

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

States a specific verb (Create) and resource (folder/directory), plus recursive semantics. An agent can tell it apart from read/remove/move siblings by the verb, though it doesn't explicitly name any sibling for differentiation.

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 when-to-use guidance and no alternatives are named despite many path-related siblings (list_directory, copy_path, move_path, remove_path). The idempotency note ('existing folder is fine') is behavioral, not routing 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=true, openWorldHint=false), it discloses two non-obvious behaviors: missing parent folders are created automatically, and an existing destination is never overwritten, which materially softens the destructive profile an agent would otherwise assume. It also notes per-item reporting for batch calls. It does not cover partial-failure semantics or permissions.

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

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

Three tight sentences: capability first, then behavioral guarantees, then the batch-mode routing hint. No filler and every clause 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?

With no output schema, the description reasonably covers return behavior by noting each item in a batch call is reported individually, and the annotations cover the safety profile. Remaining gaps are minor: no statement about partial failures, path format expectations, or how the single-item vs batch forms interact.

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

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

Schema coverage is only 40% (deviceId and workSessionId are described in the schema; from/to/moves are not), but the description supplies the key extra meaning for `moves`: a list of {from, to} pairs, cap of 200, used for bulk organizing. The meaning of from/to for the single-item form is left to inference, which is adequate but not enriched.

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

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

The description opens with a specific verb+resource pair ('Move or rename files and folders') and immediately adds batch scope, so the agent knows exactly what domain this acts on. It does not name or contrast sibling operations like copy_path or remove_path, so it falls short of full sibling differentiation.

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 concrete usage pattern and a routing rule: use the single from/to form for one item, and pass `moves` with up to 200 pairs 'to move many items (organizing a folder)'. It stops short of naming alternatives or stating when NOT to use this tool (e.g. copy vs move, delete vs move).

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds real behavior beyond that: a newline is appended by default (overridable), and blocking with waitMs/waitForPrompt changes the return to JSON output. It still doesn't explain what 'destructive' means here (typing into a live process) or what happens without a wait.

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

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

Two tight sentences with no waste; the primary action and its default side effect come first, and the conditional return behavior follows immediately.

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

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

With no output schema, the description does explain the conditional JSON return, which is helpful. But for a 7-parameter destructive tool it omits what happens in the non-waiting case, error/ambiguity behavior, and the session/device prerequisites, leaving gaps an agent must guess at.

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

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

Schema description coverage is only 29% across 7 params. The description usefully explains the newline default and the waitMs/waitForPrompt effect, and deviceId/workSessionId carry their own schema descriptions, but it adds nothing for 'input'/'id' formatting or the waitMs ceiling (30000). Baseline 3 for a low-coverage schema that is only partially compensated.

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 ('Type text into a start_process session') and names the target session type, which distinguishes it from siblings like process_output and run_command. It does not explicitly contrast itself with those siblings, so it stops short of a 5.

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

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

Implies the usage context (driving an interactive start_process session) and hints at when to use the wait options, but never states when to choose this over process_output, run_command, or stop_process, nor any preconditions like needing a live session.

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

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

Annotations already declare readOnlyHint=true and no destructive behavior, so the safety profile is covered. The description still adds real behavioral context beyond annotations: the wait/exit semantics of waitMs, the heuristic nature of waitForPrompt, the tailChars default, and the shape of the returned JSON. It omits auth/rate-limit context, but it discloses useful operational behavior.

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

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

Dense but efficient: purpose is front-loaded, then conditional-option semantics, then the default, then the return shape in a single sentence. Nearly every clause carries information; no filler.

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

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

With no output schema, the description usefully enumerates the returned fields (running, exitCode, output, nextCursor, interactionState), covering the return-value burden. Combined with the wait semantics, an agent has enough to call it correctly; only the cursor/length/offset pagination parameters are left unexplained.

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

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

Schema description coverage is only 20%, so the description must carry parameter meaning. It does explain four parameters well (newOnly, waitMs, waitForPrompt, tailChars), but leaves cursor, length, and offset entirely undocumented in both schema and description, so pagination behavior is unclear. Partial compensation, not full.

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 the output and status of a start_process session'), immediately distinguishing it from siblings like process_input, start_process, stop_process, and list_process_sessions. An agent can tell what it does and what it does not do without opening any schema.

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

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

The description explains the semantics of the waiting options (newOnly, waitMs, waitForPrompt) but never states when to choose this tool over siblings such as check_operation or process_input, nor any explicit when-not conditions. Usage is only implied through the option descriptions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully carried by structured data. The description adds only the scoping detail that the clipboard content is text, and says nothing about empty-clipboard or format behavior. With annotations covering safety, a 3 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?

A single front-loaded sentence with zero padding and the resource stated immediately. It is efficient, though its brevity borders on under-specification for a tool that can target multiple devices.

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

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

For a simple read-only tool with full annotation coverage, a 100%-covered schema, and no output schema, the description is minimally adequate. It omits any note on return format or empty-clipboard handling, which is a minor but real gap.

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

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

Schema description coverage is 100%, and the two parameters (deviceId, workSessionId) are thoroughly documented in the schema itself, including the guidance to reuse the same workSessionId per conversation. The description adds no parameter meaning beyond that, so baseline 3 applies.

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

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

States a specific verb and resource ('Read text from the computer's clipboard'), which clearly distinguishes it from the sibling write_clipboard. It is unambiguous, though it does not name the sibling explicitly the way a top-tier definition would.

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 offers no when-to-use context, no prerequisites, and no mention of alternatives or failure conditions. Nothing tells the agent when this read is appropriate versus, say, reading a file or a browser snapshot.

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

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

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint, so the safe-read profile is covered. The description adds genuine behavioral detail beyond that: the exact return header format, per-format interpretation of offset/length, and the OCR modes. It omits rate limits and permission/auth requirements, but for a read tool this is a solid addition.

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

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

Front-loads the core verb, then uses a compact per-format structure that lets each clause earn its place. It is dense and somewhat run-on, but appropriate given 14 parameters and five supported formats.

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

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

With no output schema, the description usefully documents the returned reading-header format, which many such tools omit. It is largely complete, though a handful of lower-level parameters (maxBytes, maxImages, extractImages, docxPart) are left undocumented across both schema and description.

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

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

Schema coverage is only 14%, so the description must carry the load, and it does: it defines offset/length semantics for text (zero-based line, default 1000, negative offset reads last N), clarifies they count pages for PDF, and documents options.ocr, docxMode, sheet, and range. Several params (maxBytes, maxImages, extractImages, docxPart, isUrl) remain unexplained in either place, keeping it from a 5.

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 ("Read a file") and then enumerates the content types it handles (text, images, PDF, DOCX, spreadsheets), so an agent understands the true scope. It also explicitly distinguishes itself from the read_url sibling for web pages.

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

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

Gives clear context for when to use it and names one alternative explicitly ("For web pages use read_url"). It does not, however, address the other sibling it overlaps with (read_multiple_files) or when to prefer bulk reads, so guidance is present but not exhaustive.

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

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

Annotations already declare readOnlyHint/destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: per-file error isolation ('its own error if it fails') and that offset/length apply uniformly to every file. It does not cover maxBytes defaults or truncation behavior.

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

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

Two dense sentences, front-loaded with the scope and cap, then the error-isolation and format/param semantics. No filler.

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

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

With no output schema, the description usefully sketches the return shape (per-path headers, per-file errors). For a 6-parameter tool it still leaves maxBytes semantics and the handling of partial failures ambiguous, but the essentials for correct invocation are present.

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

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

Schema description coverage is only 33%: deviceId and workSessionId are documented inline, but offset, length, and maxBytes are not. The description usefully clarifies that offset/length apply to every file, which the schema does not convey, but maxBytes remains undocumented in both places.

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?

Clear verb (Read) plus resource (multiple files) with explicit scope: up to 20 files, each under its own path header. It references read_file for format compatibility, which hints at the sibling relationship, but it never states the routing rule for choosing one over the other.

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?

Batch usage is implied by 'in one call' and the 20-file cap, but there is no explicit when-to-use / when-not-to-use guidance and no mention of when to prefer plain read_file or a search tool instead. An agent must infer the routing.

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

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

Beyond the annotations (readOnly/openWorld/non-destructive), the description discloses meaningful behavioral traits: no cookies or credentials are sent, a 1 MB read cap, refusal of private/local addresses, and the IPv6-public caveat. This is exactly the extra context an agent needs and cannot get from the schema or annotations.

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

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

A single dense paragraph that is front-loaded with the core purpose and then the constraints, with zero filler sentences. Every clause (format handling, offset/length, security posture, size cap, network restriction) earns its place.

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

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

With no output schema and 7 parameters, the description does strong work explaining format conversion and safety behavior, but it doesn't describe the shape of the returned content (e.g., line numbering or truncation signaling) that an agent would need to consume results 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 only 29%, so the description has to compensate, and it partially does: it explains offset/length ('select lines') and the read-size cap. However deviceId, timeoutMs, workSessionId, and the exact semantics of maxBytes are left to the schema, so the low coverage is not fully offset.

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 precise verb+resource ('Read a public web page or HTTP(S) URL') and even specifies the transformation semantics (HTML to text, JSON/XML/text as-is). It clearly conveys what the tool does, but never names a sibling (e.g., read_file, browser_open, browser_snapshot) to disambiguate within the crowded read/browser toolset.

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 constraints ('public', 'Refuses private and local network addresses') rather than stated as when-to-use guidance. It never says when to prefer this over read_file or the browser_* tools, and gives no exclusions beyond the network-address restriction.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds the crucial extra fact that the operation 'cannot be undone' and clarifies recursive semantics, but does not mention recoverability via undo_file_change or any permission requirements.

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

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

Two tight sentences, front-loading the destructive warning immediately after the core action with zero 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 destructive tool with no output schema, the description covers action, irreversibility, recursion, and the usage precondition. It is nearly complete, lacking only notes on recoverability or scoping interactions with work sessions.

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

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

Schema coverage is 50%: deviceId and workSessionId are documented in the schema, while path is self-evident and the non-obvious 'recursive' flag is explained in the description ('true for a folder with contents'). This meaningfully compensates for the coverage gap on the parameter that most affects 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?

States a specific verb ('Delete') and resource ('file or folder'), immediately distinguishing it from the copy/move/list siblings. An agent can tell what this 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?

Gives a clear condition: 'use it only when the user asked for the deletion.' That is an explicit when-to-use rule. It does not name alternatives such as move_path or undo_file_change, so the sibling differentiation is not complete.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the risk profile is known. The description adds genuinely useful context beyond them: it runs as the logged-in user and may need Accessibility permission for UI control. It does not, however, mention return behavior, error handling, or the destructive implications of arbitrary script execution.

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

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

Two short sentences, front-loaded with the core action and followed by the one operational caveat. No filler, though it is arguably too terse for a code-execution 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?

With no output schema, the description carries the burden of explaining what the tool returns, and it says nothing about script output, exit status, or failure modes. For an arbitrary-code-execution tool this is a meaningful omission.

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

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

Schema coverage is 67%, with deviceId and workSessionId well documented in the schema and script self-evidently the code to execute. The description adds no parameter-level meaning, so it neither compensates for the gaps nor improves on 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?

The description states a specific verb and resource ('Run AppleScript') plus the execution identity (logged-in macOS user), which is clear enough to understand the tool. However, it does not distinguish itself from the close sibling run_command, which an agent could reasonably pick instead.

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 guidance and no mention of alternatives such as run_command or browser_action. The only contextual cue is the accessibility-permission note, which hints at UI-control scenarios but stops short of routing the agent.

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

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

Annotations already flag readOnlyHint=false, destructiveHint=true and openWorldHint=true, but the description adds the operational specifics an agent needs: execution as the signed-in user, a 50 s threshold after which the command survives as a process session, the default timeoutMs of 120 s, and that the reply carries an id usable with process_output/stop_process.

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

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

Front-loads the core behavior and exit-code format, then the fallback routing. Dense but every clause carries routing or behavioral information; only the long sibling enumeration at the end risks being skimmed.

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

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

With no output schema, the description still explains the return value (combined stdout/stderr plus [exit=N]) and the async escape hatch. For a destructive, open-world command runner with only one required parameter, nothing essential is missing.

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

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

Schema coverage is only 50%, so the description should carry more of the parameter burden. It explains the timeoutMs default and the process-session interaction, but says nothing about cwd, priority, deviceId or workSessionId, leaving those to the schema text. Partial compensation only.

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 (Run) and resource (shell command) with the exact return shape (combined stdout/stderr ending with [exit=N]). It distinguishes itself from siblings by naming start_process, read_file, list_directory, search_files, search_content, edit_block, write_file, system_info, disk_usage and list_processes as separate concerns.

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: use start_process for jobs longer than the timeout and for commands that wait for input; use the dedicated file tools for reading/listing/searching/editing; use the read-only system tools for machine inspection. This is when-to-use, when-not-to-use, and named alternatives in one paragraph.

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?

Adds substantial context beyond the annotations: validates every step before any run, stops on first error, requires read/write/process permissions, completed steps are not rolled back or replayed, and commands are bounded by their normal timeout. These are exactly the behavioral traits an agent needs before triggering a destructive, open-world run.

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

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

Front-loads the core action, then layers constraints in information-dense sentences; nearly every sentence earns its place. It is long, but the complexity of the tool justifies most of it.

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

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

No output schema exists, yet the description names the return value (runId) and the lifecycle around it (poll or cancel). Combined with permission and timeout disclosure, an agent has everything needed to invoke and reason about the call.

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?

At 40% schema coverage the description usefully compensates for three of the parameters: inputs, the selected workSessionId, and expectedVersion's provenance and purpose. deviceId is left to the schema, and the description doesn't explain input key/value semantics, so it's strong but not complete.

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

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

States a precise verb (start one run) and resource (a saved workflow) with the input model made explicit. It clearly distinguishes itself from siblings get_workflow (review), workflow_status (poll), and cancel_workflow (stop), so an agent can route without ambiguity.

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 conditions: pass expectedVersion from get_workflow to refuse a stale definition, then poll workflow_status or cancel_workflow. It routes to the right follow-up siblings, though it does not explicitly state when NOT to use this tool versus a direct step call.

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

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

Beyond the destructiveHint annotation, it discloses that saving executes nothing, that definitions/inputs are stored locally rather than in the relay, that secrets must not be included, and that supplying workflowId replaces the caller's earlier definition without keeping prior steps. This is exactly the extra behavioral context annotations cannot convey.

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

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

Front-loaded with the core purpose and then layers constraints efficiently; every sentence adds information (templating, local storage, scheduling, replacement). Dense but not padded, though the long parenthetical tool list makes it heavier than strictly necessary.

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-param tool with no output schema and partial schema coverage, the description is thorough on inputs, storage, security, and replacement behavior. It does not indicate what the call returns (e.g., a workflowId for later use), which is the one notable gap.

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

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

Schema coverage is only 33%, so the description carries meaningful load: it explains the steps structure (one call to a listed tool with that tool's own arguments), the {{inputName}} templating for later value substitution, fixed-text command constraints, and the replace-on-workflowId semantics. Only name/description params remain undocumented, but they are self-evident.

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 (Save) and resource (ordered workflow steps on this computer), and immediately distinguishes itself from run_workflow and schedule_workflow. An agent can identify this as the definition-storing tool without opening any schema.

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

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

Explicitly frames the use case ('to rerun later with run_workflow') and rules out the common confusions: 'saving runs nothing' and 'saving sets no schedule; schedule_workflow... runs a saved workflow on one.' It names the alternative and the condition that selects 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?

Annotations only give the safety envelope (readOnlyHint=false, destructiveHint=true, openWorldHint=true); the description goes well beyond by disclosing required permissions (read, write, process), the server-side retention of inputs with an explicit 'never put secrets in them' warning, the notification policy and its default, version-pinning/abort behavior, and shared permission inheritance with run_workflow.

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

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

Dense single paragraph with the core action front-loaded and no filler sentences; each sentence carries distinct operational information (preconditions, secrets, notifications, return values, permissions). Slightly overloaded as one block rather than separated concerns, which costs it the top score.

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 8-parameter mutation tool with nested objects and no output schema, the description covers returns ('scheduleId and the next run time'), permissions, failure/notification behavior, environment requirements, and the version-safety contract. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains the semantics of expectedVersion (each run uses exactly that version), the default of notify ('failures, the default'), and the server-side storage of inputs. It does not, however, add anything on time/timeZone formatting or deviceId resolution beyond the schema.

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

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

Opens with a specific verb+resource+scope: 'Run a saved workflow on a schedule ... with no chat open', immediately distinguishing it from run_workflow (immediate execution), get_workflow (read) and list_scheduled_workflows (enumeration). An agent can select it 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?

Explicitly prescribes the prerequisite sequence ('Review it first with get_workflow and pass the version it showed as expectedVersion') and names the sibling it parallels ('runs it on that computer the way run_workflow does, with the same permissions'). It also states the when-not condition: it 'does not start if the workflow has changed', and the environment precondition that the computer must be on and connected at that time.

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

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

Annotations already declare readOnly/non-destructive/non-open-world, so the safety profile is covered. The description adds real behavioral context beyond annotations: the Mac Screen Recording permission requirement and the lossy-vs-lossless tradeoff between jpeg and png. It does not disclose what is returned (path, base64, dimensions), 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?

Three short sentences, zero filler, front-loaded with the core action followed by the alternative-tool routing. Every clause carries information an agent can act on.

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

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

For a simple read-only capture tool with three optional params and no output schema, the description covers the action, format tradeoff, permission prerequisite, and sibling alternative. The one gap is the return shape (no output schema exists to explain it), which would matter for handling the captured image.

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 67%, with deviceId and workSessionId already documented in the schema and format's enum/default declared. The description only adds 'png for lossless' on top of the enum, which is marginal. Baseline 3 is appropriate given the schema does most of the work.

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

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

States a specific verb and resource ('Capture the computer's screen as a JPEG image') plus a scope qualifier (whole computer screen, not browser content). It explicitly names the sibling browser_snapshot and the case where that sibling is preferable, so an agent can distinguish 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?

Gives clear context: use for the computer screen generally, use browser_snapshot for web pages in the connected browser, and note the Mac permission prerequisite. It stops short of saying when this tool should NOT be used at all (e.g., multi-monitor selection), so it is strong but not fully exhaustive.

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

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

Annotations only declare the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false); the description adds substantial context beyond that: a few-frames-per-second screen feed, the Take control hand-off, the privacy guarantee that 'what they type there never reaches you', and the required OS permission. The one gap is that the control-session framing is not reconciled with readOnlyHint=true, leaving mild ambiguity about whether the call itself only mints a link.

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 clause and each subsequent sentence adds non-redundant information (user capabilities, privacy, follow-up screenshot, platform/permission limits). The opening sentence is somewhat dense with its colon-list, but nothing is filler.

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

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

With no output schema, one fully documented parameter, and annotations carrying the safety profile, the description supplies everything else an agent needs: when to invoke, the hand-off mechanics, the follow-up action, and the environment prerequisites. It also makes clear the tool yields a link to be handed to the user.

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

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

Schema description coverage is 100% for the single deviceId parameter, which already explains 'computer name or id from list_devices; optional with one computer'. The description only implies device targeting ('one of their computers') and adds no syntax or selection detail, so the schema does the heavy lifting – the baseline 3.

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 action on a specific resource – produce a live-control link for one of the user's computers – and even distinguishes the workflow from its sibling by telling the agent to 'take a screenshot to see where things stand' afterward. An agent can tell this apart from 'screenshot' without opening either schema.

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

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

It names concrete situations that select this tool ('to sign in, pass a CAPTCHA, approve a payment or anything else only they should do') and states the post-condition workflow: wait until the user reports they are done, then screenshot. Preconditions (works on Macs, needs Live screen permission owned by the machine's owner) are explicit.

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

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

Annotations already establish read-only and non-destructive behavior, so the description earns credit for adding search-specific context: skipping hidden files, .git, and node_modules unless includeHidden; regex behavior per line; and the returned match shape plus contextLines. It still omits important behavioral details such as result limits and case-sensitivity defaults, which are only discoverable from the 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 description is front-loaded with the core purpose and packs a lot of useful detail into one dense but efficient passage. It could be slightly easier to scan, but there is little wasted 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?

For a 10-parameter tool with a nested limits object and no output schema, the description does well to explain the return format and search scope. However, it leaves out limit behavior and case sensitivity, so an agent cannot fully understand parameter effects from the description alone.

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

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

Schema description coverage is only 20%, so the description must compensate. It usefully explains path, query, regex, includeHidden, filePattern, and contextLines, but it never mentions limits, caseSensitive, deviceId, or workSessionId, leaving key parameters undocumented in both places.

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: 'Find text inside files', which is clear and distinguishable from file-listing or file-reading siblings. It does not explicitly distinguish itself from the sibling search_files, 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 explains search mechanics but gives no explicit when-to-use guidance or named alternatives. It does not tell the agent when to choose this over search_files or read_file, or when it is inappropriate.

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

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

Goes well beyond the readOnly/openWorld annotations: discloses the 8-second scan deadline, the macOS Spotlight index fallback, the truncated-result behavior with scanComplete false elsewhere, and the maxResults cap. These operational quirks are exactly what an agent needs to interpret partial results.

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

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

Front-loads the core operation and matching rules, then handles return value, timeout, and the specificity tip in order of importance. Dense but every clause carries information; the final sentence is long but justified by the fallback nuance.

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

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

Despite no output schema, the description specifies the return shape (JSON array of full paths) and the truncation/scanComplete semantics. Combined with the parameter coverage, an agent has everything needed to call and interpret this tool 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 only 40%, so the description must compensate — and it does for query (substring vs glob syntax with examples), path (default resolution), and maxResults (default 100). The remaining two params (deviceId, workSessionId) are covered by their own 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 (Find) and resource (files and folders by name), and immediately scopes the matching semantics (case-insensitive substring, glob when * or ? present). It is clearly distinguishable from siblings like search_content (contents) and list_directory (enumeration).

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 usage conditions: path defaults to the work session workspace or ~, and advises giving the most specific folder to avoid the 8-second timeout truncation. It does not explicitly name an alternative (e.g. search_content for contents) so routing is implied rather than stated.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false), so the bar is lower, and the description adds real behavioral content: write in the user's own words and never include file contents, credentials, or personal data they did not ask to share. It does not describe confirmation, delivery, or rate-limit behavior, so it stops 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?

Three tight sentences with the purpose front-loaded, then trigger conditions, then content constraints. Each sentence carries weight; the only minor cost is that the privacy constraint sentence is somewhat long.

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 fire-and-forget send with no output schema, the description covers purpose, triggers, and content constraints adequately. It does not indicate whether the user should be given confirmation or how the send is delivered, a small gap for a 3-parameter mutation.

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

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

Schema description coverage is 100%, so the schema already documents kind, rating, and message semantics. The description restates the enum meanings and the 'in the user's words' constraint but adds no syntax or format detail beyond the schema, making the baseline 3 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 (send) plus the resource (the user's feedback about BCD to the BCD team) and enumerates the kinds handled (bug, feature request, praise). No sibling tool does anything comparable, so an agent can distinguish it immediately.

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

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

Explicitly states the two triggering conditions: 'when the user asks to report something to BCD, or accepts your offer to.' It also constrains the message content, which is the relevant 'how' guidance here since no alternative tool competes for this task.

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

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

Annotations only supply the generic readOnly/openWorld/destructive flags, but the description adds specifics an agent cannot get elsewhere: link lifetime (60 minutes default, up to 24 hours), the constraint that the host computer must be online, that anyone with the link can download, that the file streams through BCD in pieces and is not retained, and the required read permission. No contradiction with the annotations.

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

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

Five short sentences, front-loaded with purpose and the critical output instruction ('Give the user the url'), followed by the expiration/online constraints, the security caveat, and the permission requirement. 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?

With no output schema, the description correctly tells the agent what to hand back (the URL). It covers durability, availability, security exposure, data handling, and required permissions for a genuinely open-world operation, so nothing essential is missing.

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

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

Schema coverage is 100%, so the schema already documents path, minutes, and deviceId, including bounds. The description restates the expiry default and ceiling, adding light context for 'minutes,' but does not touch deviceId selection or the 2 GB limit beyond the schema.

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

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

The description opens with a concrete verb and resource: 'Make a link that downloads one file from a computer,' plus the user-facing purpose (open on phone or pass on). The download direction is inherently distinct from the upload_link sibling, so an agent can route correctly without opening either schema.

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

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

It gives clear context (share to a phone or hand off a link) and an explicit guardrail: 'make one only for a file the user asked to share.' It does not, however, name an alternative tool or say what to do when a durable transfer is needed rather than a link.

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