Computer-Use Agents API

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses idempotency ('a no-op if it does not exist or already finished'), but says nothing about whether cancellation is graceful or immediate, what happens to in-flight work, or any auth requirements.

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

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

A single compact sentence with the core action front-loaded and the idempotency caveat attached. Nothing is wasted and nothing is buried.

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

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

An output schema exists, so return values need not be described, and the description covers purpose plus idempotent behavior. For a one-parameter tool this is nearly complete, with only the mechanics of cancellation and the parameter meaning left unstated.

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

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

Schema description coverage is 0% and the description never explains session_id, leaving the parameter undocumented in both places. The meaning is inferable from context (the session to cancel), but nothing beyond that is added.

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 ('Cancel a session'), so an agent immediately knows the operation. However, it offers no differentiation from siblings such as wait_for_session or share_session, though none of them overlap with cancellation.

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

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

Usage is only implied: the tool is for cancelling a session, and the idempotency clause hints at when calling is harmless. There is no explicit when-to-use, prerequisite, or alternative-tool 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?

With no annotations, the description carries the full burden. It does disclose a meaningful behavioral trait: results are permission-scoped to what the caller can run, plus public h/ agents. However, it says nothing about pagination behavior (the page/size params imply paged results) or read-only semantics beyond what "List" implies.

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 no filler; the scope qualifier follows the object it modifies. Appropriately sized, though it is arguably too terse to cover pagination.

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

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

An output schema exists, so return values need not be described. For a simple read-only listing tool this is close to adequate, but with no annotations and no pagination guidance, an agent can't tell how to page through results.

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

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

Schema description coverage is 0% and both parameters (page, size) are undocumented in the schema. The description adds nothing about paging or result limits, so it fails to compensate for the coverage gap.

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

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

The description states a specific verb and resource ("List agents") and scopes it precisely: agents the caller can run, including the org's own plus public h/ ones. That scope nuance is genuinely informative. It doesn't differentiate from siblings, but the sibling set (session/file/session controls) doesn't overlap, so no confusion arises.

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 or when-not-to-use guidance and no named alternative. The phrase "agents the caller can run" vaguely implies you call this to discover runnable agents before using run_agent, but that inference is left entirely to the agent.

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

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

No annotations exist, so the description carries the full burden. It discloses real behavioral traits beyond the schema: newest-first ordering, that listings can be truncated, and that paging must use both modified_before and name_after because timestamps tie. It does not mention permissions/auth or error behavior, keeping it out of 5 territory.

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, followed by two short paragraphs that each justify themselves: one prevents a wrong session_id, one prevents a broken pagination loop. No filler sentences.

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

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

An output schema exists, so return values need no prose, and the description covers scope, ordering, and the non-obvious paging contract for a five-parameter tool with no annotations. It stops short of complete because auth/permission requirements and failure modes are 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%, so the description must supply meaning, and it does for the three most ambiguous parameters: session_id's origin, and the paired semantics of modified_before/name_after as an ISO-8601 + tiebreaker cursor. path and max_entries are left to their schema defaults and get no explanation here.

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

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

States a specific verb and resource ('List files on a browser session's machine') and adds ordering ('newest first'), which immediately distinguishes it from the sibling read_file. An agent can tell what it does and roughly what it returns 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 clear operational context: the exact provenance of session_id ('issued by env-manager... not the id run_agent returns'), which prevents a very likely wrong-argument mistake, and explains exactly when to use the pagination params. No explicit when-not or named alternative (e.g. read_file) is given, so it stops short of a 5.

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

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

With no annotations supplied, the description carries the full burden, and it does add real value by disclosing the return shape (base64 content plus metadata). However, it says nothing about error behavior (missing file, permission denied), size or binary/text limits, or whether the read has side effects.

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 disambiguation note placed after; no filler. Slightly dense phrasing ('browser session's machine') but nothing wasteful.

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

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

An output schema exists, so return values need not be re-explained, and the session_id provenance is covered. Still, for a 2-required-parameter tool with no annotations and 0% schema coverage, the meaning of 'path' and the error/mutation profile are left 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%, so the description must compensate. It usefully disambiguates session_id's provenance (env-manager, not the id run_agent returns), but leaves 'path' entirely undefined as to whether it is absolute, relative, or relative to what root.

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

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

States a specific verb and resource ('Read a file from a browser session's machine') and even describes the return payload (base64 content and metadata). It does not explicitly differentiate itself from siblings like list_files or write_file, but the operation is unambiguous on its face.

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 on when to choose this over list_files, run_agent, or write_file, and no prerequisites or failure conditions are mentioned. The session_id note is parameter clarification rather than usage routing, so the agent is left to infer the context.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses the two possible outcomes (immediate answer vs. session handle to wait on), which is real behavioral information. It says nothing about side effects, cost, permissions, whether execution is asynchronous/background, or how idempotency_key affects retries.

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 clauses, front-loaded with the action and followed by the result contract. No filler, though the extreme terseness is part of why key parameter details are missing.

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

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

An output schema exists, so return-shape detail is not strictly needed, and the description covers that adequately. But with 5 parameters at 0% coverage and no annotations, an agent cannot tell what max_steps/max_time_s do or what idempotency_key guarantees — significant gaps for a tool that launches autonomous execution.

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% across 5 parameters, so the description must compensate. It only clarifies one parameter's origin ('agent' from list_agents); task, max_steps, max_time_s, and idempotency_key are left entirely undefined, including units and semantics (steps? seconds? retry key?).

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 ('Start an agent on a task') and even summarizes the dual-shaped result (answer or session handle). It distinguishes itself from the read/list siblings, though it does not contrast with wait_for_session or send_message 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 phrase 'agent from list_agents' is a useful prerequisite pointer, and 'session handle to wait on' implies the wait_for_session follow-up. However there is no explicit when-to-use guidance, no when-not, and no statement about how this differs from send_message to an existing session.

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

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

No annotations are provided, so the description carries the full behavioral burden. Beyond noting the target must be a 'running session', it says nothing about whether the call blocks, whether it queues behind an in-flight turn, permission requirements, or failure modes for a non-running session.

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 no filler and the key scope qualifier ('running session') placed where it matters. It is efficient, though arguably too terse for the information the agent needs.

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

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

An output schema exists, so return values need not be explained here. For a two-parameter tool that is nearly acceptable, but the absence of any parameter documentation and of routing guidance relative to run_agent/wait_for_session leaves real 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 should compensate but does not. It never clarifies what 'message' should contain (role, format, whether it is delivered mid-turn) or what form 'session_id' takes or where it comes from.

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 ('Send a follow-up message') and scopes it to 'a running session', which separates it from siblings like run_agent (which starts a session) and wait_for_session. It does not explicitly name those siblings, so differentiation is inferential rather than stated.

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

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

'Follow-up' implies this is for continuing an already-running session rather than creating one, which is useful implicit guidance. However, it gives no explicit when-to-use versus run_agent, no prerequisites (e.g., that the session must be awaiting input), and no exclusions.

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

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

With no annotations, the description carries the full burden. It does disclose a meaningful behavioral trait — that the session becomes publicly readable (a visibility change with privacy implications) and that a share URL is returned. However, it says nothing about authentication requirements, whether the change is reversible, or what happens if the session is already public.

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

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

A single front-loaded sentence that states the effect and the return value with 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?

An output schema exists, so return-value detail is not required. For a simple one-param tool this is close to adequate, but with no annotations and no when-to-use or reversibility context, an agent lacks enough to invoke it confidently in edge cases.

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 parameter session_id is undocumented in both schema and description. The name is self-explanatory and the tool is trivial (one required string), so the gap is small, but the description adds no meaning beyond the schema.

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

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

States a specific verb and resource ('Make a session publicly readable') plus the concrete outcome (returns the absolute share URL). It is clearly distinguishable from siblings like cancel_session or read_file, though it never names a sibling explicitly.

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

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

There is no guidance on when to use this versus alternatives, nor any conditions or prerequisites. The intent is only implied by the verb 'share', leaving the agent to infer the trigger scenario.

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

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

With no annotations, the description carries the full burden, and it does disclose the key trait: this is a polling/long-poll operation that blocks when `wait` is true. It stops short of timeout duration, what happens on timeout, or error behavior, which matters for a blocking call.

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

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

A single tight sentence with the mode split front-loaded after the verb; no filler and no repetition of schema or title.

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

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

An output schema exists, so return values need not be explained, and the two operational modes are covered. The gap is blocking semantics: how long the long-poll waits and what it returns on expiry is exactly what an agent needs for a blocking call and is absent.

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

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

Schema coverage is 0%, so the description must compensate, and it does for the non-obvious parameter: `wait` is explained as long-poll vs. current snapshot, which the bare boolean in the schema cannot convey. `session_id` is left unaddressed but is self-evident by name.

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 (poll) and resource (a session), and splits behavior by the `wait` flag, so an agent knows this retrieves session state. It does not name or contrast any sibling (e.g., why not send_message or run_agent), which keeps it out of 5 territory.

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

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

The description implies when each mode applies (long-poll for the answer vs. grab the snapshot), which is genuinely useful routing guidance. However, it gives no explicit when-to-use/when-not-to-use context relative to siblings, and never states prerequisites such as the session needing to be running.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose that content must be base64-encoded and that writing happens on a remote browser session's machine, but it is silent on whether an existing file is overwritten, what permissions or failures are possible, and whether parent directories are created.

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 action and scope, followed by the single most likely point of confusion (which session id). No filler or repetition 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?

An output schema exists, so return values need not be described, and the session_id caveat is valuable. But for a mutation tool with zero annotation coverage and 0% schema description coverage, the description omits overwrite semantics and path interpretation, leaving 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 coverage is 0%, so the description must compensate, and it does explain session_id's provenance in detail — a genuinely non-obvious point. However, 'path' is left entirely unexplained (absolute vs relative, whether directories are auto-created), and content_base64's encoding is only implied by the opening clause.

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 with scope: 'Write base64-encoded content to a file on a browser session's machine.' It goes further by disambiguating the session_id from the id returned by run_agent, so an agent can distinguish the two identifiers 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?

The second sentence implies correct usage by specifying which session id to pass, which is real guidance, but it never states when to use this tool versus siblings like read_file or list_files, nor any preconditions (e.g., session must exist, file may be overwritten).

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