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

Annotations already establish readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context: it reports 'actual' (runtime, not configured) state, and the caveat that 'Unavailable capabilities do not prevent connection' discloses partial-availability semantics an agent would not otherwise infer.

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, with the subject and scope front-loaded and the availability caveat placed second where it belongs. 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 and no parameters, the description still enumerates the returned fields (capabilities, targets, control owner, pause state), which is what an agent needs to know what it will get back. It does not describe the shape or format of those values, a minor 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?

The schema has zero parameters (additionalProperties: false), so per the rubric the baseline is 4. The description appropriately spends no words on parameter syntax it does not have.

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

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

The description names a specific verb ('Read') and enumerates the exact resource set: enabled capabilities, targets, control owner, and pause state, scoped to 'this approved connection'. That is far more specific than a tautology, though it never names or contrasts against a sibling such as ai_report, so the 5 tier for sibling differentiation is not met.

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 statement of when to call this versus alternatives, no prerequisites, and no when-not-to-use condition. The phrase 'for this approved connection' frames the subject but does not tell an agent when this tool is the right choice over ai_report or the apps_* family.

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 establish a non-read-only, open-world, non-idempotent, non-destructive profile. The description adds behavior beyond that: it is usable during the Allow AI wait and after approval, output is length-bounded and language-matched, and there are explicit content prohibitions (no commands, secrets, reasoning). These are meaningful traits the annotations do not encode.

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 with zero filler. The core action is front-loaded and the constraints follow immediately; 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 simple one-param notification tool with no output schema, the description covers purpose, timing, and content limits adequately. The only minor gap is that nothing indicates whether repeated calls are expected or how the report is surfaced, but the annotations handle 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 coverage is 0%, so the description carries the burden for the single 'message' param. It does add substantive content constraints — one or two brief sentences, the person's language, no raw commands/secrets/internal reasoning — which materially shape what goes into the field. It stops short of naming the field or its 280-char limit, but the semantics are well conveyed.

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 (Report) and resource (the current action, result or next step) plus the addressee (the person) and format (one or two brief sentences in their language). It is immediately clear what the tool does. It doesn't need sibling differentiation since no other ai_* tool overlaps, but it also doesn't route against anything 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 gives real timing context — it works both while waiting for Allow AI and after approval — which tells the agent when the tool is callable. However it never states when to report vs. stay silent, nor references any alternative mechanism, so the usage guidance is implied rather than 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 flag destructive=true, non-idempotent, and openWorld, so the safety profile is covered. The description adds substantial context beyond that: how down/up/cancel versus click/long behave, the holdMs default pairing, the special K1=host Menu behavior, and the control-loss cancellation semantics. It stops short of describing return/status behavior, but this is strong added value.

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

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

Three dense sentences, front-loaded with the core action before the phase mechanics and constraints. Almost every clause earns its place; only minor density in the middle sentence keeps it from a 5.

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

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

For a 7-parameter, 5-required mutation tool with no output schema and zero schema descriptions, the description covers the main workflow and control semantics but omits meaning for several parameters (delta, generation, instanceId) and any notion of the response. It is adequate but not complete.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It does explain the type semantics (down/up/cancel as exact phases vs click/long as paired presses) and the holdMs default, and it maps the control enum to keys. However, delta, generation, instanceId, and the target values receive no explanation, leaving a significant compensation 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?

The description opens with a specific verb ('Simulate') and a precise resource (E1-E4 rotation/press and K1-K4 keys) plus the target scope ('explicit active preview or device App'). This scope clearly differentiates it from siblings like apps_interface_input and apps_preview_input, so 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?

It implies the usage context ('on an explicit active preview or device App') and states a prerequisite ('Requires AI control'), which hints at when it applies. However, it never names an alternative tool or an explicit when-not condition, so routing versus siblings like apps_preview_input is left to inference.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write profile is known. The description adds genuine non-obvious behavioral context: it returns the workspace's actual cwd, and notably that it does NOT change the shared shell directory — a subtle side-effect distinction an agent needs. It doesn't cover auth/rate limits, but the cwd clarification is valuable.

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

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

Two compact sentences, both front-loaded with the key facts (creation and cwd behavior). No filler, 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 creation tool with annotations covering the safety profile, the description covers the essential behavioral quirk (cwd behavior). However, with no output schema and no usage guidance among many siblings, the description is only minimally complete — an agent gets the 'what' but not the 'when' or param details.

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

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

Schema description coverage is 0% and there is only 1 param ('name'), so per the rule baseline is 4 for zero params, but here 1 param exists. The description adds nothing about the 'name' parameter's format, uniqueness, or constraints. Schema is minimal (just a string), and the description compensates not at all.

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 new App workspace.' This distinguishes it from apps_open, apps_list, apps_publish etc. among the siblings. It does not explicitly contrast with any sibling, so it's clear but not maximally differentiated.

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 guidance about when to use this versus alternatives. With 15 sibling apps_* tools, an agent would benefit from knowing when to create a new workspace vs. open/launch an existing one, and that guidance is 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 already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely new context by scoping what survives ("Preserves the shell, access, App files and saved data") and by warning that the operation is not safely replayable, which sharpens the meaning of the destructive/non-idempotent hints.

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 that front-load the action and scope, then append preserved state and post-interruption guidance. No filler, though the parenthetical scope phrasing 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?

For a mutation tool with strong annotation coverage and no output schema, the description covers the important behavioral edges: what survives the exit and what to do after an interruption. The remaining gap is the undocumented parameters, which the description should have 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 0% for two parameters (instanceId, operationId), so the description must compensate and largely does not. It implies "the specified current device App" maps to instanceId but says nothing about operationId, its purpose, or how it relates to apps_operation_status.

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 (Exit) and resource (device App) plus a scope qualifier (within the invitation's Launch/Exit scope), which clearly distinguishes it from siblings like apps_launch and apps_open. It doesn't name an alternative sibling explicitly, but the purpose is unambiguous.

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

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

"Read apps_state after interruption; never replay blindly" gives real operational guidance about the post-condition and a caution against blind retry, which is useful. However, it never states when to choose this tool over apps_control, apps_launch, or other lifecycle siblings, so the core when-to-use routing is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is largely covered. The description usefully adds that no save or editing control is needed, but it omits the non-obvious consequence of idempotentHint=false — that each call may produce a distinct snapshot — which an agent retrying would want to know.

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

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

Two tight sentences with no filler, and the purpose is front-loaded before the non-requirements. Minor demerit for the vague 'Fix' phrasing, which spends words without adding clarity.

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 tool with two required, entirely undocumented parameters and no output schema, the description should carry the load of explaining the digest requirement and the snapshot lifecycle. It instead covers only what the annotations already imply, leaving the agent under-informed at call time.

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

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

Schema description coverage is 0% and the description says nothing about either parameter. 'expectedPackageDigest' is especially opaque: an agent has no hint what digest format to supply or where it comes from, and appId is only inferable from the tool name. The description fails to compensate for the schema 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?

The description names the resource (a snapshot of an already saved App) and the intent (feeding file_download), which is more than the bare name offers. However, the verb 'Fix a read-only snapshot' is ambiguous wording that an agent could read as repairing rather than creating, and it never states plainly that it begins an export operation.

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 clause 'Does not Save or require editing control' implies when to prefer this over apps_save, and the mention of file_download implies the downstream workflow. But it never explicitly says 'use this when exporting a saved app' nor names apps_save as the alternative, so the guidance is only implied.

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

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

Annotations already declare write, destructive, non-idempotent and open-world, so the safety profile is covered. The description adds real value beyond that: the operation is atomic, it refuses to publish/save/execute, and the sha256 parameter acts as a precondition guard against clobbering a changed file — behavior an agent cannot infer from the annotations alone.

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

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

Three short sentences, front-loaded with the operation, then the override rule, then the scope exclusions. Every sentence adds distinct information with no repetition or 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, non-idempotent mutation with no output schema, the description covers purpose, the sha256 precondition, and scope limits, which is close to what an agent needs. The remaining gap is that 'reference' and 'workspaceId' are undefined, and the description never states what the call returns on success.

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

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

Schema description coverage is 0% for four parameters, so the schema supplies no meaning. The description carries part of the load by explaining expectedSha256's two modes and implying path is relative, but workspaceId and reference are entirely unexplained, leaving two of four parameters opaque.

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 ('Atomically deliver a completed app-workspace upload to a relative workspace path') and explicitly disclaims the sibling actions publish, save and execute, so an agent can separate it from apps_publish and apps_save. The verb 'deliver' is slightly abstract compared with a plain 'commit/write the uploaded file', which keeps it from being maximally crisp.

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 conditional rule for the key decision: omit expectedSha256 for a new file, supply the existing file sha256 to replace it. It also signals the precondition that the upload must already be 'completed'. It stops short of naming when to prefer this over file_upload or apps_save in a workflow sense.

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, idempotentHint=false, so the safety profile is covered. The description still adds non-obvious behavior: the export is a fixed snapshot, it returns a reference plus sha256, and it does not alter the preview or persist the App - which is what makes readOnlyHint plausible for a tool named 'export'.

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

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

Three short sentences, front-loaded with the core action, then the return contract, then the negative constraints. No filler and nothing repeated from the schema 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?

There is no output schema, but the description compensates by naming what comes back (reference and sha256). Combined with the alternative-tool routing, an agent has enough to call it correctly; only workspaceId's origin remains unstated.

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

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

Schema description coverage is 0%, so the description must carry the load. It does specify that 'path' is a relative file within the App workspace, and implies workspaceId scopes it, but it never explains workspaceId's format or how to obtain it, leaving the second required parameter underspecified.

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+resource: 'Create a fixed download snapshot of a relative file in the current App workspace.' It explicitly states the scope (relative file, current App workspace) and names the sibling it hands off to (file_download), so it is distinguishable from apps_file_commit, apps_export_begin and the file_* tools.

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

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

It routes explicitly: 'use file_download with app-workspace' for retrieval of the produced reference, and it draws exclusions with 'Does not change preview or save the App.' Both when-to-use and what-it-does-not-do are stated, rather than 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 already declare destructive=true, openWorld=true and non-idempotent, and the description adds genuinely new behavioral facts: the gating check against ai_capabilities, the prohibition on caller-supplied script/selectors, and a post-call verification step. It stops short of saying what state may be destroyed or how failures surface, which keeps it off a 5.

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

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

Front-loads the gating condition and prerequisite before the mechanics, and nearly every sentence carries a distinct constraint. The phrasing is dense to the point of being terse, but there is no filler.

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

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

For a destructive, open-world UI automation tool with four required parameters, nested event object and no output schema, the definition covers gating, coordinate frames, input modalities, exclusions and verification. The remaining gap is the meaning and provenance of instanceId/generation and what a call actually returns, which is only hinted 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 coverage is only 25%, so the description must carry weight; it does clarify the most error-prone semantics (normalized 0..1 coordinates over the whole host window, scroll in CSS pixels, allowed key set). However instanceId and generation are never explained, only indirectly pointed at via 'Read apps_input_targets first,' leaving two of four required params semantically thin.

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 pair ('Open and operate Menu or Device for the active device App') with a clear scope qualifier. It implicitly separates itself from the App-viewport sibling by stressing coordinates are relative to the 'ENTIRE host window ... not the App viewport,' though it never names apps_interface_input outright, so the distinction requires inference.

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 hard preconditions ('only when ai_capabilities.hostMenus enables that surface and AI owns control'), an explicit prerequisite ('Read apps_input_targets first'), and negative scope ('Does not operate permission/AI approval, access-management or lifecycle controls'). An agent knows both when to call it and when to skip 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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is largely covered. The description adds a meaningful behavioral trait: the commit is guarded by the previously issued package digest, implying a staleness/concurrency check. It stops short of saying what is overwritten or what permissions are required.

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

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

A single front-loaded sentence with the verb first and no padding. Efficient, though it is arguably too terse for a destructive four-parameter tool.

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

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

For a destructive, non-idempotent mutation with four parameters, 0% schema coverage and no output schema, the description is thin: it omits what a successful commit produces, the meaning of reference/operationId/confirmed, and any rollback or irreversibility context. The digest precondition is the only depth provided.

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

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

Schema coverage is 0%, so the description must carry the param burden. It glosses expectedPackageDigest ('previous package digest') and gestures at the decision behind 'confirmed', but says nothing about 'reference' or 'operationId' — half the parameters remain unexplained, leaving the agent guessing at required string formats.

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 ('Commit an inspected App package') and links the action to a prior inspection step plus a digest and an approved decision. It reads as a distinct commit step in an inspect-then-commit workflow, though it never names the sibling tools (apps_import_inspect, apps_file_commit) it is adjacent to.

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

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

'Inspected' and 'its previous package digest' imply a prerequisite inspection step and a prior approved decision, which hints at the workflow. But there is no explicit when-to-use or when-not-to-use statement, no named alternative, and no mention that commit should only follow apps_import_inspect.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true). The description usefully adds that the tool returns conflict/confirmation state and that it does not itself import, but the 'Validate/Inspect' framing sits awkwardly beside readOnlyHint=false and the description never explains that side effect or its open-world 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 sentences, front-loaded with the purpose and followed by the return/behavioral note, with no filler. The semicolon-linked caveat reads slightly compressed but still 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?

No output schema exists, so the description partially compensates by naming the returned conflict/confirmation state and clarifying it is not the import step. However, the two input parameters, the preconditions, and the reason for the non-read-only hint remain unaddressed for a stateful import-workflow 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 0% with two parameters (reference required, operationId optional), so the description must carry the burden. It never defines what 'reference' denotes (despite the phrase 'its inspected reference') nor mentions operationId at all, leaving both parameters effectively undocumented.

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

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

The description states a specific verb and resource: 'Validate a completed .vrchapp app-package upload,' and clarifies the return (inspected reference plus conflict/confirmation state). It distinguishes the inspect step from the import step ('file_done alone never imports an App'), though it never names the sibling tool apps_import_commit 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 clause 'file_done alone never imports an App' implies this is a pre-import validation step and hints at its place in the import workflow, but it never explicitly says when to call this versus apps_import_commit or what precondition (an uploading upload) must hold.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: coordinates are normalized to the App viewport and are independent of the device's 150% browser zoom, plus an explicit statement that no preview launch/link/switch occurs. It omits anything about refresh/caching or how often the bindings should be re-read.

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 zero filler: the primary action and its timing come first, the coordinate contract second, and the negative boundary last. Every clause earns its place.

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

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

With no output schema, the description identifies what is returned (active preview and device App bindings) but not the shape of that payload, so an agent cannot fully anticipate the response. Annotations and the coordinate contract cover the rest, so the gap is modest rather than blocking.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The coordinate-normalization note is about the coordinate system the caller must use downstream, which is useful even though it is not a parameter of this call.

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 (the active preview and device App bindings), and scopes it as a pre-input step. It differentiates itself from mutation siblings like apps_preview_input and apps_control by declaring it only reads bindings, though it does not explicitly contrast with apps_state, which an agent might confuse it with.

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?

"before input" gives a clear timing/context cue, and "Does not launch, link or switch the person's preview" functions as an explicit when-not boundary. It stops short of naming the sibling tool to call afterward (e.g., apps_preview_input, apps_interface_input), so routing is implied 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 destructiveHint=true, idempotentHint=false and openWorldHint=true, and the description adds genuinely new behavior: delivery only confirms 'sent/dispatched events' rather than actual effect, and guide_start 'does not approve access or I/O'. It does not spell out what state a mis-aimed click could destroy, but the dispatch-vs-effect caveat is the key risk note for this tool.

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

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

Five compact sentences, action list front-loaded, then prerequisites, exclusions, and verification in descending priority. No filler or restatement of the title.

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

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

For a destructive, non-idempotent input injector with no output schema, it covers prerequisites, permission boundaries, delivery semantics, and how to verify results. The remaining gap is the meaning of instanceId/generation (staleness guards for a mutation), which an agent must infer.

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 the description fills the most important gap by defining pointer coordinates as normalized App coordinates and scroll deltas as CSS pixels, which the schema does not say. The event type list is echoed from the nested event schema, and instanceId/generation remain undefined 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?

The description opens with a concrete verb set (click, drag, scroll, type, key/chord) scoped to 'the active device App interface', which is specific enough to select it against apps_host_input and apps_operation_status. It stops short of naming apps_preview_input as the alternative for preview-only flows, so sibling differentiation is only partly explicit.

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

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

It gives explicit routing ('Use apps_host_input for Menu/Device'), a prerequisite ('Read apps_input_targets first'), an exclusion ('Permission dialogs remain human-operated'), and a verification path ('use screenshots/App state to verify'). That is when-to-use, when-not, and alternatives all 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?

Annotations declare mutation and open-world behavior, but the description adds substantial context: the Launch/Exit scope, capability granting flow, human-required browser/OS and Allow AI permissions, and the fact that it does not save a draft. These are exactly the behavioral details an agent needs beyond the annotations.

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

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

The purpose is front-loaded and every sentence adds operational guidance, with no filler. It is dense with conditional clauses, but that density is functional rather than wasteful.

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

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

The description covers the complex capability-negotiation path and permission boundaries well, but with no output schema and very low schema description coverage, it leaves critical required parameters like expectedPackageDigest unclarified. An agent still lacks full invocation semantics for a mutation tool of this complexity.

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

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

Schema coverage is very low at 14%, and the description compensates for only some parameters: replaceInstanceId, manifestDigest, requestedCapabilities, and allow are explained conditionally. Required parameters appId and expectedPackageDigest, plus operationId, remain unexplained in both schema and description.

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: launch or focus a saved App within the invitation’s enabled Launch/Exit scope. This distinguishes it from state-reading siblings like apps_state and from exit behavior, though it does not explicitly differentiate from apps_open.

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 prerequisites and conditional usage: read apps_state first, use replaceInstanceId only after deciding to replace a known target, and retry with allow:true after a capability_required response. It does not name which sibling to use for alternative launch/open scenarios, keeping it below 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description usefully adds that retained drafts are included and that the scope is the invited host, but says nothing about pagination despite the cursor parameter, which is a notable omission for a list operation.

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 short sentence with zero filler, and the operation verb is front-loaded. Nothing is repeated from the title or schema.

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

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

With annotations covering the read-only/idempotent safety profile and no output schema, the description only needs to add operational context. It omits pagination behavior and sibling differentiation, so it is minimally adequate 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 description coverage is 0% and the single cursor parameter is completely undocumented in both schema and description. The description must compensate for this gap but never mentions pagination, result-size limits, or how to obtain the next cursor.

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 ('List Apps and retained drafts') plus the scope 'on the invited host', which is clearer than a bare name restatement. It never differentiates itself from the many apps_* siblings, especially apps_state, so an agent must guess whether listing differs from reading state.

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, no prerequisites, and no named alternative among the ~29 sibling tools. 'On the invited host' is the only scoping hint, leaving the agent to infer when this is preferable to apps_state or apps_operation_status.

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 openWorldHint=true, idempotentHint=false, destructiveHint=false, covering the safety profile. The description goes further with non-obvious side-effect detail: it returns cwd, never overwrites a draft, and never sends cd to the shared PTY — a real behavioral constraint an agent could not derive 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 tight sentences with the core action front-loaded and the behavioral caveats following. Every clause carries information; no filler or restating of the tool 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?

For a state-mutating tool with no output schema and 0% parameter coverage, the description partially covers behavior and return value (cwd) but omits all parameter meaning and offers no guidance versus apps_launch/apps_create. It is workable but leaves the invocation details to guesswork.

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

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

Schema description coverage is 0% and the description says nothing about either parameter. In particular, expectedRevision appears to be a concurrency/optimistic-locking control and appId's expected format is unstated, so the description fails to compensate for the documentation gap in a 2-parameter tool.

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

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

States a specific verb and resource ('Open an existing App or retained draft'), which is enough to distinguish it from apps_create or apps_publish. However, it does not differentiate itself from the close sibling apps_launch, which an agent would also associate with opening/running an app, so sibling differentiation is incomplete.

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?

'Existing App or retained draft' implies the tool only applies to already-created resources, so usage is implied rather than stated. It names no alternative (e.g. apps_create for new apps, apps_launch for running one) and gives no preconditions or exclusions, leaving the agent to infer routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, covering the safety profile. The description adds the notion of a durable result and a caution against replaying mutations, but does not explain result format, durability limits, or error 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 sentences, front-loaded with the core purpose and followed by a critical usage caution. Every sentence earns its place and there is no wasted wording.

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 0% parameter description coverage, the definition should explain what arguments to pass and what the durable result contains. It leaves both the required parameters and the return value entirely undocumented, making it insufficient for reliable invocation.

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

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

Schema description coverage is 0% and the description does not mention either required parameter. The parameter names are somewhat self-explanatory, but the definition adds no meaning about expected values or role of originalOperationId and originalAction.

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 (Query) and resource (durable result of an interrupted App action). It is clear what the tool does, but it does not explicitly differentiate itself from sibling tools like apps_state or apps_control.

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 context: use this after an interrupted App action to query the durable result, and explicitly cautions against automatically replaying a mutation. However, it does not name alternative tools or conditions for choosing among them.

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 destructive=false/readOnly=false? — specifically readOnlyHint=false, destructiveHint=true and openWorldHint=true, covering the safety profile. The description adds real behavioral context beyond that: the operation requires current AI editing control and is confined to the preview, not the device App. It does not detail what state mutations occur, so it is strong but not exhaustive.

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

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

Two lean sentences, front-loaded with the action and immediately followed by the precondition and exclusion. No filler or redundancy, though it could have spent its brevity on documenting the event payload.

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 taking an opaque nested event object with no output schema and no parameter documentation, an agent lacks the information needed to construct a valid call. The description covers scope and auth but leaves the core payload shape entirely unaddressed.

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

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

Schema description coverage is 0% and the 'event' parameter is a free-form nested object whose shape is undocumented anywhere. The phrase 'normalized control or pointer event' hints at event semantics but adds no structure, format, or meaning, and workspaceId is not explained at all. With such low coverage, the description fails to compensate.

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

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

The description gives a specific verb (send) and resource (normalized control or pointer event) and scopes it clearly with 'to the connected preview only.' It implicitly separates this from device-level siblings like apps_launch or apps_control by stating it cannot control the device App, though it does not name an explicit alternative.

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

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

It states a concrete prerequisite ('Requires current AI editing control') and an explicit exclusion ('cannot launch or control the device App'), which tells the agent both when and when-not to use it. It stops short of naming a sibling alternative to reach for instead, but the routing conditions are clear.

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

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

Annotations already declare this is a destructive, non-readonly, non-idempotent, open-world operation. The description adds useful behavioral context: it publishes the exact draftRevision and a failed target load preserves the old applied revision, which helps an agent understand failure semantics.

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

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

Two tightly written sentences with zero waste. The precondition is front-loaded and the failure behavior is a useful second sentence, so every part 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 destructive publish operation with no output schema and 0% schema description coverage, the description covers failure semantics and timing but leaves parameter meanings and expected success behavior unexplained. Annotations cover safety, but the remaining gaps prevent a higher score.

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

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

Schema description coverage is 0%, so the description must carry parameter semantics. It mentions 'draftRevision' but does not explain the required 'expectedRevision', 'workspaceId', or optional 'operationId' parameters, and the terminology mismatch could cause confusion.

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 ('publish') and resource ('exact draftRevision'), and the timing precondition helps clarify scope. However, it does not explicitly say what is being published or distinguish the tool from siblings like apps_save or apps_preview_input, and the pronoun 'its' lacks a clear antecedent.

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 provides a clear precondition: use after all files and build steps in a complete editing round finish. But it does not state when not to use this tool or name alternatives such as apps_save or apps_preview_input.

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 destructive=true, idempotent=false, readOnly=false, and openWorld=true, so the safety profile is covered. The description adds real value with 'atomically' and the warning to separate package-save success from preview/device application results, but it says nothing about the optimistic-concurrency behavior implied by expectedRevision or what a failed atomic save leaves behind.

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 primary action front-loaded and no filler. The second sentence earns its place by disambiguating two result channels, though it reads as terse CLI-style prose rather than an explainable definition.

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?

This is a destructive, non-idempotent mutation with a required concurrency parameter, no output schema, and no parameter documentation — and the description omits the failure/retry story, permission requirements, and the relationship to apps_publish. Given that complexity, two sentences are not enough for an agent to call it safely.

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

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

Schema description coverage is 0%, so the schema documents no parameter meaning at all and the description must compensate — it does not. None of operationId, workspaceId, or expectedRevision are named or explained, and expectedRevision in particular is a concurrency token whose semantics are essential and entirely undocumented.

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

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

States a specific verb and resource ('Publish the completed draft and atomically save its .vrchapp package'), which is far more concrete than a tautology. However, it does not distinguish itself from the sibling tool literally named apps_publish, leaving genuine ambiguity about which one an agent should call.

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 statement of when to use this tool versus apps_publish, apps_preview_input, or apps_control, all of which plausibly overlap. The only guidance is interpretive ('Separate saved package success from preview/device application results'), which tells the agent how to read results, not when to invoke the 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, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds the operationally valuable warning that file-transfer success is not evidence the application was applied, which is real behavior guidance beyond the annotations; it does not describe response shape or staleness semantics.

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

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

Two sentences, no filler, with the resource scope front-loaded and the corrective instruction second. 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 usefully enumerates what is read back (draft, revisions, actual target states) and covers the safety posture via annotations. The remaining gap is the unexplained optional appId, which matters given the tool is also callable with no arguments.

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 single parameter appId has 0% schema description coverage and is not required, yet the description never mentions it and does not say what happens when it is omitted (active app assumed) or how it relates to "the active App draft." The scoping of this ambiguous optional parameter is left entirely to inference.

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 a clearly enumerated resource set: active App draft, desired/saved revisions, and actual target application states. It is distinguishable from mutation siblings like apps_save/apps_publish, though it never names them or any alternative 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?

"Read this after interruption" gives an explicit trigger condition, and "do not infer application from file transfer success" supplies a concrete exclusion/warning about a wrong inference path. It stops short of naming an alternative tool for cross-checking 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 state this is not readOnly, not idempotent, and not destructive, but the description adds no context beyond what the annotations already imply. It doesn't explain whether the transfer can be resumed after cancel, what happens to partial data, or whether the cancellation is immediate. For a mutation tool with zero parameter documentation and no output schema, the description should carry more behavioral burden than it does.

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 sentence with no filler. It front-loads the action and resource without wasting words.

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

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

For a no-parameter mutation tool, the description is minimally adequate but leaves key operational questions unanswered: what qualifies as 'current', how to identify the transfer, and whether cancellation is reversible. These gaps matter for safe invocation, though the simplicity of the tool limits the damage.

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

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

Zero parameters, so the baseline of 4 applies. The description correctly implies no user-supplied input is needed to identify the transfer to cancel.

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 (Cancel) and resource (current shared file transfer), which is clear enough to distinguish from siblings like file_pause and file_resume. However, it doesn't explicitly differentiate 'cancel' from 'pause' beyond the verb choice, 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?

No guidance on when to use cancel versus pause or when-not to use it. The reader must infer that cancel terminates while pause suspends. No prerequisites, permissions, or alternative is named.

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

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

The description adds real behavior beyond the annotations: full byte verification and an atomic, no-overwrite commit, which tells the agent existing files will not be clobbered and partial writes won't be left behind. It does not disclose failure modes (what happens on verification failure or partial transfer), whether the transfer is resumable, or how the download interacts with the sibling pause/resume/cancel tools, all of which matter for a non-idempotent, open-world write.

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

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

One dense sentence, front-loaded with the action and destination, with the integrity/atomicity guarantees trailing as qualifiers. Nothing is padded, though the compression contributes to the jargon problem.

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

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

For a five-parameter, non-idempotent, open-world file-writing tool with no output schema and no documented return values, the definition covers the core guarantee but omits how to obtain a 'reference', what operationId is for, and how progress/failure is surfaced. An agent could invoke it, but not confidently handle limits or recovery.

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

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

Schema coverage is 0% across 5 parameters, so the description bears the burden. It partially covers 'path' ('a new local path') and 'reference' (the App package reference to download), but says nothing about 'purpose' (app-package vs app-workspace), 'maxBytes' (capped at 128 MiB), or 'operationId', leaving three parameters with no semantics anywhere.

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

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

The description names a concrete verb (Download), a resource (an authorized App package reference), and a destination (a new local path), so an agent can tell it moves data onto the local filesystem. The phrasing 'authorized fixed App package reference' is jargon that is never defined, and no sibling (file_upload, apps_file_export, apps_file_commit) is mentioned for contrast.

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

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

There is no statement of when to use this rather than file_upload, apps_file_export, or apps_file_commit, and no mention of the file_pause/file_resume/file_cancel companions that clearly relate to long transfers. The only usage signal is indirect, via the word 'authorized', which hints that callers are pre-approved but never says how.

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

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

Annotations already declare mutating (readOnlyHint=false), idempotent, non-destructive, open-world behavior, so safety is covered. The description adds only that it targets the "current" transfer, meaning no transfer handle is supplied — useful, but it omits whether the pause is resumable or how long it persists.

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. It is on the terse side — one clause about the resume path would fit without bloat — but nothing is wasted.

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

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

For a zero-parameter state toggle with solid annotation coverage, this is close to sufficient. It still leaves the scope of "current" ambiguous (which transfer, whose) and never links to file_resume, the tool an agent will almost certainly need next.

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

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

Zero parameters, so the baseline is 4. The description's "current" clarifies that the target is implicit ambient state rather than an identified resource, which is the one meaningful thing an agent needs to know 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?

Clear specific verb+resource: "Pause" plus "shared file transfer". It contrasts naturally with siblings file_resume and file_cancel, though it never names them. An agent can tell what it does without opening the schema.

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

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

No when-to-use guidance beyond the verb itself, and no mention of the counterpart tools file_resume/file_cancel or the condition that would pick each. The only usage cue is the word "current", which is inferred 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 readOnlyHint=false, idempotentHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the scoping detail that it acts on the 'current shared file transfer,' but does not disclose preconditions, error behavior, or what happens if no transfer exists.

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, front-loaded sentence with no filler or repetition. It states the action and target directly, earning every word.

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, non-destructive state-change command, the description is minimal but adequate to identify the operation. However, it omits usage context, preconditions, and what the tool returns, leaving gaps that matter for correct invocation despite the low complexity and available annotations.

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

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

The tool takes zero parameters, so the baseline is 4. The description does not need to explain parameter meanings, and it correctly implies the tool operates on a current transfer without requiring any inputs.

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

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

The description states a specific verb and resource: 'Resume the current shared file transfer.' It clearly distinguishes the action from siblings like file_pause, file_cancel, file_upload, and file_download, even without explicitly naming them. However, it does not explicitly differentiate itself from all siblings or state its scope beyond 'current shared'.

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 guidance, no prerequisites, and no alternatives. It implies the tool resumes an existing transfer but does not state whether the transfer must be paused, active, or failed first. An agent must infer all invocation 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 write (readOnlyHint=false), open-world, non-idempotent, and non-destructive. The description adds two useful behavioral traits beyond that: the transport is resumable, and app packages remain private until inspect/commit. It does not cover failure modes, auth, or resumption details.

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 core action and followed by the key constraint. No redundant or filler content.

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

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

A mutation tool with 4 parameters, 0% schema description coverage, and no output schema needs a fuller description to be safely invoked. The current text leaves most parameters and behavioral details (resumption, error handling, workspace scoping) 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 0%, so the description must compensate. It vaguely implies that 'path' is a local file and 'purpose' relates to app packages, but operationId and workspaceId are entirely undocumented. Most of the parameter semantics are left to the schema's enum and types alone.

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 (upload) and resource (local regular file) and names the transport mechanism. It distinguishes itself from file_download by implication and mentions inspect/commit for app packages, but does not explicitly contrast with any sibling tool.

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 constraint for app packages (.vrchapp, private until inspect/commit) which implies a workflow, but does not state when to use this tool vs alternatives like file_download or apps_import_inspect. Usage is only partially implied.

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

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

Annotations already declare readOnly, non-destructive and openWorld, so the safety profile is covered. The description adds meaningful context beyond that: the interaction with the human Multi-screen setting, the batch-as-separate-images return, and the explicit note that it does not alter input control. It does not address the idempotentHint=false implication (screens can change between calls), which is a minor gap.

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

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

Four short sentences, all load-bearing, with the core action front-loaded before the setting/parameter caveats. No filler or redundancy, though the final sentence is a niche caveat rather than essential 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, and the description compensates by describing the return ('complete batch as separate images'). With one optional parameter, no required params, and annotations covering the safety profile, an agent has everything needed to invoke this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it clarifies that 'primary' or a display connector is only selectable 'While on' and that connectors come 'from prior image metadata' — details not present in the schema text. Only one optional parameter, so there is limited room to add more.

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

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

States a specific verb and resource ('Capture the device screens once') and immediately clarifies the return shape ('complete batch as separate images'). It is unambiguous what the tool does, though it never names or contrasts a sibling (the sibling list contains no other screenshot tool, so differentiation is less critical).

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?

Explains the triggering conditions for behavior: the default follows the human Multi-screen setting, and the 'screen' parameter is only relevant while that setting is on. It also states a non-behavior ('Does not change input control') that helps an agent decide it is safe to call. No explicit alternatives are named, but none exist among the siblings.

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

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

The annotations declare destructiveHint=false, but the description explicitly says the tool discards unsubmitted input and that submitted input cannot be retracted. That is a direct conflict about the tool's destructive effect, so this is scored 1 and flagged as an annotation contradiction.

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 permission condition and then covers effects, preconditions, and post-call inspection. Every sentence adds operational meaning without waste.

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

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

For a sensitive cancel/interrupt operation with no output schema, the description covers preconditions, side effects, parameter meaning, and post-interruption inspection. It is complete enough for an agent to call it safely.

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

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

There is one parameter and the schema provides no description for it, so the description carries the full burden. It explains exactly when resumeAI should be true: only when the person also authorizes continuing AI 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?

The description states a specific verb and resource: cancel the current private input. It also clarifies scope by saying it happens without reading or submitting the input, which distinguishes it from terminal_input and related terminal operations.

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

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

The description gives strong when-to-use guidance: only when the person explicitly asks. It also conditionally gates resumeAI and advises inspecting state after interruption, though it does not name sibling alternatives.

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

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

Annotations only cover safety hints (readOnlyHint=false, openWorldHint=true, non-idempotent, non-destructive). The description adds the genuinely important behavior: a one-time human approval is required, and what that approval actually grants (observation, on-demand screenshots, AI editing, or input control) varies by invitation type.

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 leads with the action, then the approval condition, then the per-invitation-type consequences. Dense but every clause carries information; only mild cleanup would be possible.

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 connection tool with no output schema, the approval-flow and outcome descriptions are valuable, but the two undocumented parameters and the absence of any note on reconnect/resume behavior leave meaningful gaps.

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

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

Schema description coverage is 0% for both parameters, so the description carries the full burden and does not explain what "url" should contain (invitation URL? terminal ID?) or what "resume" does. An agent cannot reliably populate either parameter from this text.

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 ("Join") and resource ("invited device Terminal"), and goes further by distinguishing invitation types and what each grants. It is clearly separable from siblings like terminal_disconnect, terminal_input, and terminal_events, though it does not name them.

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?

Describes the approval flow and the differing outcomes per invitation type, which implicitly tells the agent what to expect on invocation. However, it never states when this tool should be chosen over alternatives such as apps_launch or terminal_input, 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 idempotentHint=true and destructiveHint=false, so the safety profile is known. The description adds genuinely new context beyond the structured fields: the admitted session credential is retained and the session can be resumed within its authorization, which tells the agent the disconnect is reversible.

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

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

Two tight sentences with the action front-loaded and the resumption behavior immediately after. No wasted words.

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, annotation-backed tool with no output schema, the description covers the key behavioral question (is this destructive / can I come back?). It stops short of naming how to resume (presumably terminal_connect), which is a minor 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?

There are no parameters (0 params, schema coverage 100%), so the baseline is 4. The description has no parameter semantics to add, and none are needed.

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 ('Disconnect') and resource ('this client'), which directly contrasts with the sibling terminal_connect. It is clear what the tool does, though it does not explicitly name the sibling it complements.

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

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

Usage is only implied: you call it to end a terminal session. There is no explicit statement of when to use this versus alternatives (e.g., terminal_connect to resume) or any 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 readOnly/non-destructive/openWorld, so the safety profile is covered. The description adds real behavioral context beyond that: it blocks up to 20 seconds by default, returns early on events, and returns one complete queued capture batch with a separate image per captured screen. It does not mention rate limits or failure/empty-result behavior, keeping it short of a 5.

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

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

Four dense sentences with no filler; the core purpose and invocation pattern are front-loaded, and each remaining sentence carries either a differentiation, a timing rule, or a return-shape detail.

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

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

There is no output schema, so the description usefully describes the return shape (one queued capture batch, separate images per screen). Combined with the timing and non-screenshot clauses, it is nearly complete for a single-optional-parameter read tool, though empty/timeout behavior is left unstated.

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

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

Schema description coverage is 100% and the waitSeconds description already covers default, range, and early-return behavior. The description's 'Omit waitSeconds for the normal 20-second wait; returns early on events' restates the schema rather than adding new semantics, so the baseline 3 applies.

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

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

States a specific verb and resource ('Read terminal events and actual images shared by the human') and explicitly differentiates from the sibling take_screenshot ('Does not take a screenshot'). An agent can identify the tool's role 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 explicit invocation timing ('while waiting for ai_pending/approval and between actions') and shows the exact call form terminal_events({}). The when-to-use condition is concrete rather than implied.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and non-idempotent, so the risk profile is known. The description adds non-obvious behavior beyond that: it is gated on human authorization, it must never carry secrets, and the response automatically includes shared screenshots. It stops short of describing what terminal state the input can affect or how errors surface, so it falls just 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?

Front-loaded with the primary purpose and the controlling precondition; the credential warning and the screenshot note each carry real information. Sentences are multi-clause and dense, but no sentence is filler.

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

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

For a one-parameter destructive tool with no output schema, the description covers gating, the secret-handling boundary, the sibling alternative, and the return payload (screenshots). What remains missing is the shape/semantics of the input payload itself.

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 single 'data' parameter has 0% schema description coverage, so the description must compensate. 'Shell input' implies raw input text, but it never says whether newlines/Enter must be included, whether it is a keystroke sequence or a whole command line, or how it is truncated. Adequate inference, no more.

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

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

States a specific verb and resource (send shell input) plus the governing precondition (human-granted AI input control). It explicitly distinguishes itself from terminal_run_private, which handles the credentialed case, so an agent can route between the two without opening either schema.

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

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

Gives when-to-use (only under granted AI input control), an explicit exclusion (never passwords/tokens), and the named alternative for the excluded case (terminal_run_private with device-confirmed Private Input). Nothing about selection is left to inference.

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

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

Adds substantial context beyond the annotations: output is suppressed, the finished event carries only exitCode/reason, a privateCommand capability is required with fail-closed behavior on older devices, and there is no credential argument at all. These are exactly the non-obvious traits an agent needs before invoking a destructive, open-world command.

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

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

Six short sentences, front-loaded with the purpose and then the safety constraints; no filler. The telegraphic phrasing ("The ordinary shell is retained") is slightly clipped but still 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 still explains what the completion signal contains (exitCode/reason) and the waiting protocol, which is the key completeness gap for this tool. It does not point at terminal_cancel_private_input for aborting an in-progress private input, a minor 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 description coverage is 0%, so the description carries the burden; it does add real meaning for argv by mandating nonsecret arguments only. timeoutSeconds is left entirely to the schema (default 120, max 300), so the coverage gap is only partly closed.

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 command that needs a password or other secret using the device Private Input form") and immediately scopes it against the ordinary shell path. An agent can tell this apart from terminal_input or terminal_cancel_private_input without reading any schema.

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

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

Gives explicit when-to-use (secret-needing commands) and hard exclusions (never put a password/token in argv, terminal_input, chat or a file), plus the precondition of device-confirmed waiting_for_private_input. It does not name the sibling tools by name, so routing against terminal_input/terminal_cancel_private_input is implied 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.