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 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, non-idempotent, and open-world, so the safety profile is covered. The description adds non-obvious behavior: delivery only confirms sent/dispatched events rather than a verified outcome, and verification requires screenshots or App state. That is meaningful context beyond the structured 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?

It is front-loaded with the action verbs and then layers constraints, with each sentence carrying distinct information (prerequisite, exclusion, unit semantics, verification caveat). It is dense and slightly long, 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 high-complexity, nested-event, no-output-schema tool, the description covers modality, prerequisites, coordinate/unit semantics, exclusions, and the limits of delivery confirmation. An agent has what it needs to invoke and verify 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 50% and instanceId/generation are undocumented, but the description compensates for the input-critical parameters by specifying that pointer coordinates are normalized App coordinates and scroll deltas are in CSS pixels, which the schema does not state. The generic instanceId/generation params remain unclarified.

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 specific verbs (click, drag, scroll, type, send key/chord) and the resource (the active device App interface), so the core action is unmistakable. It also carves out the guide_start event subtype. However, it never distinguishes this tool from the sibling apps_preview_input, leaving overlap around preview inputs unresolved.

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 when to use guide_start, what guide_start does not do (does not approve access or I/O), that other host menus and permission dialogs remain human-operated, and that apps_input_targets must be read first. Prerequisites, exclusions, and the routing to the targets tool are all 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 declare the mutation and open-world profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false). The description adds genuinely useful context beyond them: the operation is bounded by an 'enabled Launch/Exit scope', new I/O permissions require human consent, and no draft is saved. It omits return/async behavior, but adds real value over the annotations.

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

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

Front-loaded with the core action, then prerequisites, then param guidance, then exclusions, in a compact set of sentences with little waste. The 'new real I/O permissions still require the person' clause is slightly opaque but earns its place as a consent caveat.

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 non-read-only, open-world mutation tool with no output schema and 0% schema coverage, the description covers scope, prerequisite, one param, and one exclusion. It leaves gaps around async behavior (operationId, apps_operation_status sibling), the required expectedPackageDigest, and idempotency, so 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% across four parameters, so the description carries the full documentation burden. It clarifies only replaceInstanceId; appId, operationId, and expectedPackageDigest (a required param, notably) receive no explanation, leaving most parameters undocumented 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?

The description gives a specific verb+resource: 'Launch or focus a saved App on the device.' The phrase 'saved App' and the focus behavior distinguish it from siblings like apps_create and apps_save, though it never explicitly contrasts with apps_open, which an agent might reasonably 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?

It states an explicit prerequisite ('Read apps_state first') and conditional guidance for replaceInstanceId ('only after deciding to replace that known target'), plus an exclusion ('Does not save a draft'). It stops short of naming an alternative tool to use when the conditions don't hold, so it is clear context without explicit alternatives.

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

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

Annotations already declare readOnlyHint=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?

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true). The description goes beyond them by disclosing byte-level verification and an atomic no-overwrite commit, which tells the agent existing files are protected. It omits async/long-running behavior that the file_pause/file_resume/file_cancel siblings imply.

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

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

A single dense sentence with the core action front-loaded and no filler. It is efficient, though the compressed phrasing trades clarity for brevity.

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

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

For a 4-parameter tool with 0% schema coverage and no output schema, the description leaves key gaps: the 'purpose' enum, the 'operationId' parameter (likely tied to apps_operation_status), and whether the download is asynchronous or returns progress are all unaddressed.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It only loosely maps to 'path' and 'reference' ('new local path', 'App package reference'); the 'purpose' enum (app-package/app-workspace) and 'operationId' are never explained.

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 clear verb (download) and resource (App package reference to a local path), which distinguishes it from file_upload. However, the qualifier 'authorized fixed App package reference' is opaque jargon that leaves the exact source object ambiguous, and it does not explicitly contrast with apps_file_export or apps_file_commit.

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 file_upload or the apps_file_* siblings, nor any prerequisites or conditions. The 'authorized' hint implies a permission gate but gives no actionable guidance.

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

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

Annotations already 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?

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 flag destructiveHint=true, openWorldHint=true and non-idempotence, and the description adds value beyond them: a human-consent gating requirement and the fact that screenshots are returned automatically. It still doesn't disclose failure behavior when input control is not granted, nor whether data is submitted raw or executed.

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

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

Two short sentences, the gating precondition front-loaded, and the response behavior second. No filler; each sentence carries distinct information.

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

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

For a destructive, non-idempotent tool with no output schema, it covers the consent prerequisite and the automatic screenshot return, which is genuinely useful. However, the undefined payload format and unstated behavior when consent is missing leave the agent guessing on the two things that most affect a correct call.

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

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

Schema description coverage is 0% and the single 'data' parameter is undocumented in both schema and description. The agent cannot tell whether data is raw keystrokes, a full command line, or whether a trailing newline is needed to execute it — a meaningful gap for the only input this tool accepts.

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 ('Send shell input'), which cleanly distinguishes it from read-oriented siblings like terminal_events and terminal_connect. It doesn't name an alternative tool explicitly, but the write/input framing makes the role 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?

Given a clear precondition: 'only while the human has granted AI input control,' which tells the agent when invocation is legitimate. It stops short of naming alternatives (e.g., terminal_events for reading output) or stating what happens if the grant is absent.

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