Phonebox

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

Annotations already declare idempotentHint=true and destructiveHint=false/readOnlyHint=false; the description corroborates and enriches this by explaining the blocking wait, the two terminal outcomes (ready vs. ended with an error reason), and that a repeat call merely waits rather than re-uploading. That retry/polling behavior is genuine value beyond the structured fields, though auth or timeout details are not addressed.

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

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

Three sentences, front-loaded with the action, then the possible outcomes, then the retry rule — no wasted preamble. The middle sentence ('It answers with the upload: ready to install with install_app, or ended with an error saying why') is slightly stilted in construction but still earns its place by covering the return states.

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

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

With no output schema, the description usefully covers the return states and the polling contract, and annotations carry the safety profile. For a two-parameter mutation tool this is nearly complete; only timeout/retry-limit expectations are 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 description coverage is 100%, with both upload_id and storage_id documented including their formats and provenance, so the schema carries the parameter burden. The description adds only the implicit point that retries must reuse the same arguments; it offers no additional syntax or format guidance, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Finish an upload'), names the precondition (file has arrived), and the side effect (Phonebox reads and stores the APK). It routes the agent to the correct sibling at each stage — create_app_upload before, install_app after — so it is clearly distinguishable from the other upload/install 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?

Gives clear context: call after the file has arrived, and call again with the same arguments if processing is still in progress. It names install_app as the follow-on step. It stops short of stating any when-not-to-use case or a maximum retry/backoff policy, so it is clear but not exhaustive.

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

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

Goes well beyond the annotations by disclosing the return payload (one-off upload_url plus an exact curl command), the handoff contract (call complete_app_upload with the storageId), and hard limits (one file, up to 500 MiB, URL valid for one hour). These are exactly the operational constraints an agent must know for a non-idempotent, open-world upload tool.

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

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

Three compact sentences, front-loaded with the action and rationale, then the mechanics, then the limits. Every clause carries information an agent needs; nothing is filler.

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

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

There is no output schema, and the description compensates by describing the return value and the follow-up call. For a zero-parameter tool whose real payload moves through a shell command, the description covers purpose, limits, and completion path completely.

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, so there is nothing for the description to disambiguate; baseline is 4. The description correctly implies no arguments are needed and instead explains the out-of-band data flow.

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 upload of your own APK') with immediate scope ('to install it on a phone'). It distinguishes itself from the sibling complete_app_upload by naming it as the required follow-up step, so an agent can place both tools in the workflow without opening a schema.

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

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

Gives clear context for use ('your own APK, such as the debug build you just made') and explicitly routes to complete_app_upload with the returned storageId. There is no explicit when-not condition or mention of the alternative install path (install_app), but the trigger and the sequencing are unambiguous.

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

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

Annotations only mark this as a non-read-only, open-world, non-destructive write; the description adds the material behavior an agent cannot infer: provisioning takes under two minutes, it bills $0.06 per minute while running, and it may return before the phone is ready. That cost and timing disclosure is genuinely decision-relevant for a spend-incurring tool.

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

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

Four tight sentences, front-loaded with what the tool does and the cost, then the operational rules. The final sentence about get_phone versus start_phone is slightly dense and requires re-reading, 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?

With no output schema, the description does the necessary work of explaining the return state (may still be creating or starting) and the follow-up call with the returned ID. It stops short of describing the full returned object, but for a 6-param, all-optional tool with full schema coverage this is close to 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 100%, so name, country, metadata, idle_timeout, max_duration, and idempotency_key are all already documented in the schema, and the description adds no parameter-level detail beyond the returned ID. Baseline 3 is appropriate when the schema carries the full parameter burden.

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 cloud Android phone") plus the completion semantics ("wait until it is ready"), which immediately separates it from siblings like start_phone, park_phone, and get_phone. An agent can identify the operation without opening the schema.

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

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

Gives explicit lifecycle guidance: always park when done, and if the phone is still creating/starting, use get_phone with its ID to keep waiting rather than start_phone, which would renew the session. It names the alternative tool and the condition that selects it, which is exactly the routing an agent needs.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds real behavioral value on top: it explains that the call can block when 'wait' is set, and reassures that it never starts, renews or bills. It does not say what happens if the wait never reaches the target state (timeout/error behavior), which is the one notable 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?

Two compact sentences, front-loaded with the core read action, then the wait behavior, then the negative scope clause. No filler and every clause carries information.

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

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

With no output schema, the description does the right thing by enumerating the returned fields (status, session, park time). Annotations carry the safety semantics. The only omission is the timeout/failure behavior of a 'wait' call that never reaches ready or parked.

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% and the enum parameter is already documented ('ready' or 'parked': wait until the phone gets there). The description's 'With wait, wait until it is ready or parked' restates the schema rather than adding format or edge-case meaning, so the baseline 3 applies.

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

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

States a specific verb and resource with scope: 'Read one phone' plus what it returns (status, session, park time). This distinguishes it from list_phones and the mutating siblings (start_phone, park_phone) without needing to open any schema.

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

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

Gives a concrete use condition: 'the way to wait for a phone that is still creating or starting', and an implicit exclusion ('It never starts, renews or bills anything'). It stops short of naming the alternative tools (start_phone/act) explicitly, so a 4 rather than a 5.

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