0bull Phone Farm

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuine behavioral context beyond them: the pipeline stops driving the phone between steps, and a not-yet-started job merely no-ops, which explains the graded effect of cancellation by state and is consistent with the idempotent hint.

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

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

Two sentences, zero filler, and the core action plus platform scope are front-loaded ahead of the edge-case behavior. 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?

There is no output schema, but the description covers the input requirement, the affected states, and the runtime consequence of cancelling, which is sufficient for a one-parameter mutation tool. It could still clarify whether the cancelled submission record remains queryable afterward, but nothing critical is missing.

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

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

With a single parameter and 100% schema description coverage, the schema already documents submission_id. The description only adds the note that the ID applies 'on any platform', which lightly clarifies that the identifier is not platform-scoped; no additional format or constraint detail is offered.

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 (cancel) plus resource (video submission) and enumerates the platforms it applies to, so an agent knows exactly what the call does. It stops short of distinguishing itself from the sibling delete-submission-tool, leaving the cancel-vs-delete boundary to inference.

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

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

It implies the applicable states (scheduled, queued, in-flight) and therefore when the tool is meaningful, which is more than nothing. But it never names the alternative (delete-submission-tool) or states when to use one over the other, so routing 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 declare a non-destructive write (readOnlyHint false, destructiveHint false, openWorldHint false). The description adds meaningful context beyond them: the account must already be signed in on the phone at the given slot, and YouTube requires google_email. It still omits failure/idempotency behavior, so it exceeds the annotation baseline without being complete.

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 primary action, then the key preconditions. No filler sentences; each clause carries actionable information.

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

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

For a 5-parameter write tool with 100% schema coverage and no output schema, the description covers the platform default, the core prerequisite, and the YouTube-specific requirement. It stops short of describing the result of a successful link, but that is the only notable gap.

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

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

Schema coverage is 100%, so each parameter (including slot, handle, platform, google_email) is already documented in the schema. The description restates the platform default and google_email requirement but adds no syntax or format detail beyond the schema — the baseline 3 is appropriate.

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

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

States a specific verb ("Link a posting account") plus the resource and the platform scope (TikTok, Instagram, YouTube). An agent can distinguish this from update-account-tool, delete-account-tool and list-accounts-tool without opening any schema.

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

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

It gives an important precondition (the account must already be signed in on the phone at the given slot), which implies when the tool applies. However, it never names alternatives or states when NOT to use it (e.g. update-account-tool for existing links, or the need to run list-phones-tool first).

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

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

Annotations already declare readOnly=false, openWorld=true, destructive=false, so the safety profile is covered. The description adds real behavioral context beyond that: the account-must-be-assigned-to-a-phone prerequisite, the exactly-one-of video source constraint, and the scheduled status lifecycle. It is silent on auth requirements, rate limits, and idempotency, 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?

Five tightly packed sentences with the core action front-loaded, then defaults/constraints, then scheduling, then the return/poll path. No filler; every sentence carries operational 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 9-parameter mutation tool with no output schema, the description covers the return value ('Returns the submission') and the follow-up polling route, plus the key prerequisites. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents defaults, mutual exclusivity, and field semantics. The description largely restates what the schema provides (tiktok default, exactly-one-of video_url/upload_id) without adding new format or syntax detail, 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 ('Queue a video to be published') plus the exact target platforms, immediately distinguishing it from sibling list/get/cancel submission tools. An agent knows this is the creation entry point 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 conditional routing: use scheduled_at to publish later, cancel a pending schedule with cancel-submission-tool, and poll get-submission-tool for the outcome; upload_id references create-upload-url-tool as its source. It never states an explicit 'do not use this when...' exclusion, but the alternative-condition guidance is clear.

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

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

Annotations only cover the safety profile (readOnly=false, destructive=false, openWorld=false). The description goes well beyond them: 15-minute expiry window, accepted HTTP methods (POST/PUT), the multipart 'video' field name, and the upload_id hand-off token. That is substantial operational context an agent cannot get from annotations.

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

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

A single, front-loaded sentence: purpose first, then the selection condition, then the exact upload mechanics and follow-up. No filler, and every clause carries actionable information.

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

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

There is no output schema, so the description must describe return values, and it does — upload_url, the 15-minute constraint, and upload_id — plus the downstream call. Nothing an agent needs to invoke this correctly is missing.

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

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

Zero input parameters, so per the rubric the baseline is 4. The description instead supplies semantics for the produced values (upload_url, upload_id) and their consumption, which is useful but outside the input-parameter remit.

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: 'Mint a short-lived signed URL for uploading a video directly.' It also distinguishes its role from the sibling create-submission-tool by positioning itself as the step that produces upload_id for it, so an agent can place the tool in the workflow without opening any schema.

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

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

Explicit selection condition: use this 'when you do not have a public video_url,' which also implicitly excludes the direct-URL path. It names the downstream alternative (create-submission-tool) and states exactly what to pass to it, leaving nothing 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 destructiveHint=true and idempotentHint=true, so the safety profile is structured. The description adds genuine value beyond that by disclosing the blast radius: the account is removed from the farm only, not from the platform itself, and by implying a permission constraint on who may manage the account.

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. The destructive scope is stated first, with the critical non-destructive clarification front-loaded in the second sentence.

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 single-parameter tool with no output schema and annotations covering the safety profile, the description supplies everything needed: what is deleted, what is preserved, and the permission boundary. Nothing material is missing.

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

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

Schema description coverage is 100% for the single account_id parameter, and the schema already documents it fully. The description adds only the platform-agnostic nature ('on any platform'), 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?

The description states a specific verb and resource ('Delete a posting account'), scopes the target platforms (TikTok, Instagram, YouTube), and crucially states what is NOT deleted (the platform-side account). An agent can distinguish this from create-account-tool and update-account-tool without opening any schema.

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

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

It implies the operation is restricted to accounts 'the authenticated user is allowed to manage' and clarifies the farm-only scope, but it never says when to choose this over siblings such as delete-submission-tool, nor does it state any prerequisites or exclusions explicitly.

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=true, so safety is covered structurally. The description adds real behavioral context beyond that: the stored video is deleted too, and the physical side effect is scoped to finished submissions across all three platforms.

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; the destructive scope is front-loaded and the constraint trails it without waste. Every clause carries information.

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

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

For a single-parameter destructive tool with no output schema, the definition covers side effects, eligibility, and scope adequately. Return behavior after deletion is not addressed, a minor 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?

Only one parameter and the schema already documents it at 100% coverage, including the 'on any platform' note. The description adds no further syntax or format detail, so baseline 3 applies.

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

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

States a specific verb (Delete) and resource (finished video submission) and enumerates the eligible statuses. It does not name the sibling cancel-submission-tool, so an agent must infer the alternative for in-flight submissions.

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

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

Gives a clear eligibility condition (published, drafted, failed, or cancelled) and an explicit exclusion ('In-flight submissions cannot be deleted'). It stops short of routing the agent to the sibling that handles the excluded case.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds a useful permission-scoping constraint ('the authenticated user is allowed to view'), but says nothing about return shape, error behavior when the account is inaccessible, or not-found handling.

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

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

One front-loaded sentence with the verb and resource first, no filler or repetition. It is efficient and appropriately sized for a one-parameter read 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 simple single-object read with one fully documented parameter, annotations covering the safety profile, and no output schema to explain, the description supplies purpose, permission scope, and platform coverage. Nothing essential is missing.

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

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

Schema description coverage is 100% for the single account_id parameter, so the schema already documents it fully. The description only echoes the 'any platform' framing found in the schema and adds no new syntax or format detail; baseline 3 is appropriate.

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

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

States a specific verb (Fetch) and resource (a single posting account), and specifies scope (accounts the authenticated user may view) and supported platforms (TikTok, Instagram, YouTube). The word 'single' implicitly distinguishes it from list-accounts-tool, but no sibling is named 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?

Usage is implied by 'a single ... account', so an agent can infer this is the one-account read versus list-accounts-tool, but there is no explicit when-to-use guidance, no mention of the alternative, and no stated preconditions beyond the permission note.

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 (readOnly, non-destructive, not open-world), yet the description adds substantial context the annotations cannot: the full status lifecycle (queued → running/waiting → done/failed/stopped), what outcome/result/error/phone_reports mean and when each appears, and a prompt-injection warning that the returned texts are agent-written reports to relay rather than instructions. That last point is high-value safety disclosure.

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 verb and resource, then layered with lifecycle and safety context in three tight sentences. It is somewhat dense but each clause carries distinct information (state machine, field semantics, injection warning), so little 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 carries the burden of explaining return values and does so thoroughly – status, outcome, result/error, and phone_reports are all accounted for. Nothing an agent needs to call and interpret this tool is missing.

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

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

There is one parameter at 100% schema description coverage, so the schema already explains run_id and its provenance. The description adds no syntax, format, or additional meaning beyond what the schema provides, 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 ('Fetch one automation run') and the singular 'one' distinguishes it from the sibling list-automation-runs-tool. It does not, however, explicitly differentiate from get-phone-run-tool, the other single-run fetch sibling.

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 schema description points to where a run_id comes from (run-automation-tool or list-automation-runs-tool), which implies the workflow context. But the description itself gives no explicit when-to-use, prerequisites, or alternative-selection guidance versus list-automation-runs-tool or get-phone-run-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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value by enumerating the possible outcomes (pending, approved, declined, failed, expired), which matters because there is no output schema.

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

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

Two tight sentences with no waste; the core action is front-loaded and the status enumeration follows immediately.

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

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

For a one-parameter read-only status checker with no output schema, the description supplies the important missing piece (the set of result states). It stops short of explaining whether the status is terminal or how to poll, but nothing essential to invoking it 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 100% and the single request_id parameter is fully described there, including its provenance from request-phones-tool. The description repeats that linkage but adds no syntax, format, or validation detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource: checks approval status of a phone-count change request. It names request-phones-tool as the filing sibling, which anchors it, but does not explicitly distinguish itself from the other billing getter (get-billing-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?

Usage is implied: call this after request-phones-tool to poll the request's status. There is no explicit when-to-use/when-not guidance, nor any statement of polling cadence or alternatives, so the agent must infer the workflow.

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/openWorldHint/destructiveHint, so the safety profile is covered. The description goes well beyond that, explaining the data model: each assigned phone is its own subscription on its own monthly cycle, `lines` carries a per-phone renewal date, and `pending_orders` charge the first month when a phone is assigned. That is meaningful domain behavior an agent could not infer from 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?

Three sentences, front-loaded with the core action, then return-field detail, then the 'start here' call to action. Dense but every clause earns its place; no filler or restated name/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?

With no output schema, the description carries the burden of explaining what comes back, and it does so concretely (per-phone renewal dates in `lines`, first-month charges in `pending_orders`). Combined with annotations covering the safety profile and zero parameters to document, nothing an agent needs to call this correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4. There are no inputs to document, and the description spends its space on return semantics instead, which is the right allocation 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 ('Read the authenticated user's phone rentals') and enumerates the returned fields (count, cost, renewal dates, pending orders). An agent can distinguish it from a generic list tool, though it never explicitly contrasts itself with close siblings like get-billing-request-tool or list-phones-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?

Ends with explicit directional guidance: 'Start here before proposing any billing change.' This tells the agent the context in which the tool should be called. It stops short of naming the alternative tools to use afterward or stating when-not-to-use it.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the description's added value is the run lifecycle state machine and the meaning of `result`/`error` for terminal states. This is genuinely useful behavior beyond the annotations, though it does not mention rate limits or polling cadence.

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 packed sentences, no filler. The core purpose and the polling instruction are front-loaded, and the result/error clarification follows only because there is no output schema to carry it.

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

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

With no output schema, the description correctly takes on the burden of explaining return values (`result.value` for get_ip and clipboard_get, `error` for failures) and the terminal statuses that signal completion. Nothing needed to call or interpret this tool correctly is missing.

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

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

Schema description coverage is 100%, so both `slot` and `run_id` are already documented in the schema, including their provenance. The description adds no parameter syntax or format detail beyond what the schema provides, 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 ('Fetch one phone run') and immediately scopes it as 'a device command, macro or GUI-agent task queued on a phone'. This distinguishes it from list-phone-runs-tool (plural listing) and from the queueing siblings like phone-command-tool and run-macro-tool without needing 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 guidance: poll until `status` is succeeded, failed or cancelled, and notes the starting states (queued then running). It does not explicitly name an alternative or say when NOT to use it (e.g. use list-phone-runs-tool to enumerate), so it stops short of full when/when-not 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 and destructiveHint=false, so the safety profile is covered by structured data. The description adds genuinely useful non-annotation context: the permission scoping ('allowed to view'), the full status lifecycle, and the fact that 'failed' carries a separate failure field. It doesn't mention errors, not-found handling, or polling cadence, which keeps it from a 5.

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

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

Front-loaded with the core action and usage directive in the first sentence, then the status reference. The status enumeration is long but each term earns its place since there is no output schema documenting them; still, it reads as a dense run-on that could be structured as a list.

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 single-resource read with no output schema, the description supplies exactly the missing return semantics: the ordered status lifecycle and the final-state set. Combined with the permission scoping note, an agent has enough to poll and interpret results correctly.

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

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

Only one parameter and schema description coverage is 100%, so the schema already documents submission_id fully – baseline is 3-4. The description adds only that the ID can refer to a submission 'on any platform,' marginal but useful disambiguation over 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 ('Fetch') and resource ('a single video submission') with explicit scope ('the authenticated user is allowed to view') and platform coverage. The word 'single' cleanly distinguishes it from the sibling list-submissions-tool without the agent needing to open either schema.

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

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

Explicitly says 'Use it to poll a submission until status is final,' which tells the agent the intended usage pattern. It does not name an alternative tool or state when not to use it (e.g., vs list-submissions-tool for bulk reads), so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context: result ordering (newest first), page size (50 per page), and the default all-platforms merge scope.

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 resource, ordering, and pagination constraint front-loaded before the platform-narrowing caveat. 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 low-complexity, zero-required-parameter list tool with annotations already carrying the safety profile, the description covers scope, ordering, and pagination adequately. It does not mention total counts or the shape of returned account records, but that gap is minor and no output schema exists to fall back on.

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 both parameters are fully documented there, including the enum values and the 'omit for every platform, merged newest-first' note. The description mostly restates page size and platform narrowing, adding little beyond the schema, 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 ('List the authenticated user's posting accounts'), scoped to three named platforms, which cleanly separates it from get-account-tool, create-account-tool, and the submission/phone listing tools. The 'authenticated user's' qualifier pins down whose accounts are returned.

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 sentence 'Every platform is included unless `platform` narrows it to one' describes scope behavior, implying the tool is for enumerating accounts across or within a platform. However, there is no explicit when-to-use guidance versus siblings such as get-account-tool for a single account, nor any stated prerequisites.

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 safe read-only profile (readOnlyHint=true, destructiveHint=false), so the bar is lower, and the description still adds real behavior: newest-first ordering, a fixed 20-per-page size, and the fact that results span all trigger origins. It does not mention auth needs or rate limits, but for a list tool with annotations covering safety this is solid added context.

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

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

A single front-loaded sentence that leads with verb and resource, then appends ordering, pagination, and scope details without a wasted clause. Highly efficient.

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 carries the return-value burden, and it discharges this economically by pointing to the shape of get-automation-run-tool. Combined with annotations covering the safety profile, an agent has everything needed to invoke it correctly, though a note on paging termination would make it 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 the schema documents both automation_id and page fully, giving a baseline of 3. The description reinforces pagination behavior (20 per page) but the `trigger` enumeration refers to a property of returned runs, not an input, and it does not clarify how paging terminates.

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

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

States a specific verb (List) and resource (runs of one of the user's automations), and explicitly contrasts with the sibling get-automation-run-tool by noting the returned items share that tool's shape. An agent can distinguish this list tool from the single-run getter and from list-automations-tool without opening any schema.

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

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

Usage is implied by the content: this is the tool to enumerate many runs. But there is no explicit when-to-use vs get-automation-run-tool statement, no note about paging through to completion, and no guidance on the trigger dimension being descriptive rather than a filter. Adequate but with a clear routing gap.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine context beyond that: automations are created/edited in the web app, and run-automation-tool only ever starts an extra run for tiktok_warmup, which tells the agent this tool is purely observational.

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

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

Front-loaded with the core purpose and reasonably tight, but the tiktok_warmup paragraph (niche, keywords, comment language, daily window, session counts) is detail-heavy for a listing tool and pushes length beyond what an agent needs to select the tool.

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

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

With no output schema, the description carries the burden of describing returns and does so: the two kinds, their differentiating fields, and the absence of `schedule_cron` for warm-ups. Nothing needed to call or interpret this tool is missing.

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

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

Zero input parameters, so the baseline is 4. The description also explains the named fields an automation carries (`prompt`, `schedule_cron`, `timezone`, `settings`), which is useful even though they are output rather than input fields.

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

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

Opens with a specific verb+resource ('List the authenticated user's automations') and immediately defines the domain object so the agent understands what an 'automation' is. It further distinguishes the two `kind` variants, making the scope unambiguous against siblings.

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

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

Explicitly names alternatives and contrasts them ('Not the same as macros (list-macros-tool), which replay recorded input exactly with no AI'), and routes follow-up work to list-automation-runs-tool and get-automation-run-tool. When-to-use and sibling differentiation are both 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 readOnly/openWorld=false/destructive=false, so safety is covered. The description adds genuine behavioral context beyond structured fields: what a macro actually is ('fixed list of taps, swipes and typing... replayed exactly, no AI'), the ownership filter, and the precedence rule that a user's macro shadows a same-named system macro.

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 sentences, all earning their place, with the core action and scope front-loaded in the first sentence. It is information-dense but not padded; the macro definition and precedence rule are the only slightly tangential asides.

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 parameterless list tool with no output schema, the description supplies what is missing: the ownership scoping, the meaning of a macro, and how to use the results downstream. Nothing essential for correct invocation is absent, though return ordering/formatting is unspecified.

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

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

Zero input parameters, so the baseline is 4. The description usefully goes further by explaining how the returned fields map onto run-macro-tool's inputs (`name`→`workflow`, `parameters`→`params`), clarifying the meaning of the output for the caller.

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 (list) + resource (recorded macros) plus precise scope: only macros the authenticated user can run, split into `owner: "you"` and `owner: "system"`. It clearly distinguishes itself from the sibling run-macro-tool by framing itself as the discovery step that feeds it.

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

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

Explicitly ties itself to run-macro-tool ('the recorded macros the authenticated user can run with run-macro-tool') and explains how to consume the output (pass `name` as `workflow`, fill `params`). It gives clear context but does not enumerate when NOT to use it, though there is no competing list sibling.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds real context beyond that: results are scoped to what the authenticated user can see, ordered newest first, and include status, result, and error per run.

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

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

Two sentences, zero filler, and the core purpose with scope and ordering is front-loaded before the alternative-tool pointer.

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 names the fields returned (status, result, error) and the ordering, which is enough for an agent to use it. It does not mention pagination behavior despite a page parameter, a minor gap.

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

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

Schema description coverage is 100% and both parameters (slot UUID, page) are documented in the schema, so the baseline is 3. The description adds no additional semantics about either parameter, though none is really 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 and resource (list runs on one phone), enumerates what a run covers (device commands, macros, GUI-agent tasks), and specifies scope, ordering, and returned fields. It is clearly distinguishable from get-phone-run-tool and list-automation-runs-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?

Explicitly routes the agent: use get-phone-run-tool to poll a single run, implying this tool is for browsing multiples. No exclusions are stated (e.g., versus list-automation-runs-tool), so it falls short of a full when/when-not treatment.

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

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

Annotations already establish readOnlyHint=true and non-destructive, but the description adds real behavioral context: the gating flag `video_live` that must be true for snapshot/OCR/control/commands/macros/agent operations, and the meaning of `can_control` as the user's drive-versus-watch permission. It does not mention pagination or result ordering, leaving 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?

Three sentences, purpose front-loaded in the first, followed by the identifier convention and the gating rules. Each sentence carries information, though the backtick-heavy second and third sentences are dense and could be split for readability.

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 parameters, no output schema and a simple list operation, the description supplies the key returned field semantics and cross-tool prerequisites an agent needs. It omits return-shape details such as pagination or list length, a small gap given there is no output schema to fall back on.

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 schema baseline is 4. The description's discussion of `slot`, `video_live` and `can_control` describes returned fields rather than inputs, which is useful but not parameter semantics per se.

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 ('List the farm phones the authenticated user can view'), and situates itself relative to the sibling phone tools by declaring it is the source of the `slot` UUID. An agent can distinguish this entry-point list tool from phone-snapshot-tool, phone-control-tool and the other phone siblings without opening schemas.

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

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

Explicitly states when this tool is required ('Every other phone tool takes the `slot` UUID from here, never the human `name`') and the precondition for downstream tools to work (`video_live: true`). It also clarifies the condition under which the current user may act on a phone via `can_control`, giving concrete when/when-not 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 readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds genuinely useful behavior beyond that — the result ordering, the 50-item page size, and the default cross-platform merge. It does not mention whether pagination terminates or how to detect the last page, which keeps it from a 5.

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

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

Three short sentences with zero waste; scope, ordering, pagination and the platform override are all front-loaded in the first two sentences. Nothing is repeated or padding.

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

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

With no output schema, the description carries return-value burden and does so partly by pointing to get-submission-tool and naming `status` and `scheduled_at`. Pagination size and ordering are covered, though total-count or end-of-list behavior is unstated, leaving a small gap for a list tool.

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

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

Schema description coverage is 100%, so both parameters are already fully documented and the baseline is 3. The description restates the platform filter's default (merged newest-first) and the page size, adding mild reinforcement but no format or syntax detail 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 ("List the authenticated user's video submissions") plus the platforms covered, ordering ("most recent first") and page size. It also distinguishes itself from get-submission-tool by defining that items share that tool's shape, so an agent can tell the two apart 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?

"Every platform is included unless `platform` narrows it to one" gives clear selection guidance for the one optional filter, and the reference to get-submission-tool clarifies the relationship to a sibling. It lacks any explicit when-not-to-use statement (e.g. versus list-accounts-tool context), so it stops short of full routing guidance.

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

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

Adds meaningful behavior beyond the destructiveHint=true annotation: async execution via a run id, success semantics ('run succeeds once the phone has run the command'), and which ops return a value. It does not spell out the destructive consequences of clear_photos or reboot or flag them as irreversible.

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 op list is tight and front-loaded as a scannable bullet block, with return-value note at the end. The header sentence plus 'op-specific fields' line adds slight redundancy but remains well under wasteful length.

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 command dispatcher with no output schema, the description covers the op set, when fields are sent, the async run-id model, and value-returning ops. That is everything an agent needs to invoke it correctly given the schema carries 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 coverage is 100%, so parameters are already fully documented. The description re-lists ops and ties op-specific fields (text, url, level, on) to their ops and notes they are only sent when provided, which is mild added value but mostly repeats the schema.

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

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

The description states a specific verb and resource ('Send a device command to a farm phone'), enumerates all 11 supported ops, and cross-references list-phones-tool for slot resolution. An agent can distinguish it from siblings like phone-control-tool or phone-snapshot-tool 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 gives a clear precondition ('The phone must show video_live: true in list-phones-tool') and how to resolve the slot UUID. However, it never explicitly states when to use phone-command-tool versus siblings like phone-control-tool, run-phone-agent-tool, or phone-ocr-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 destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds real value beyond them: input is applied directly (not queued) and the call returns as soon as the phone acknowledges it, plus the live-video precondition. It does not discuss failure modes when the phone is not live, which holds it below a 5.

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

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

Front-loaded with purpose and the sibling contrast, then a tight bulleted op list. Every sentence carries information and there is no redundancy with the 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?

For a mutation tool with no output schema, it covers the precondition, the divergence from the sibling tool, return timing, coordinate conventions, and each op's argument shape. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline would be 3. The description earns more by explaining coordinate semantics beyond the schema (fractions of the screen, 0 = left/top, 1 = right/bottom) and by grouping parameters into ops (tap uses fx/fy, swipe uses fx1/fy1/fx2/fy2/steps), clarifying which params apply to which op.

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

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

The description opens with a specific verb+resource ('Send one raw input to a farm phone') and immediately names the sibling it is not ('Unlike phone-command-tool, which queues a run'), so an agent can distinguish it without opening either schema. The op list further pins down exactly what 'input' means.

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 ('The phone must show video_live: true in list-phones-tool') and contrasts behavior with the phone-command-tool alternative (direct application vs queued run), which tells the agent which of the two to reach for. Nothing critical 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/destructiveHint=false, so the safety profile is covered, and the description still adds a genuine operational gate: the phone must be video_live per list-phones-tool. It also discloses a cost/robustness trait (cheaper than an image), which is real behavioral context beyond the annotations. Return metadata like resolution is not discussed, but width is controllable via 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?

Three short sentences, zero filler, with the action and mechanism front-loaded and the prerequisite placed last where it is easy to check. Nothing is repeated for its own sake.

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 2-parameter read tool with a 100%-covered schema and annotations carrying the safety profile, the description covers action, prerequisite, and relative cost, and notes the return is OCR text. Only marginal gaps remain (e.g., no mention of OCR failure/empty-text behavior), which is acceptable given no output schema exists.

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

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

Schema coverage is 100%, so both parameters (slot, width) are fully documented in the schema itself, including the UUID-vs-display-name rule and the video_live constraint. The description only restates the video_live prerequisite and adds no new parameter syntax or format detail. 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 the on-screen text of a farm phone' — and immediately describes the mechanism ('snapshots the slot and returns the OCR-recognized text'). The clause 'cheaper than an image when you only need the text' implicitly separates it from phone-snapshot-tool, so an agent can distinguish the two without opening schemas.

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

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

Gives a clear selection condition versus the imaging sibling ('cheaper than an image when you only need the text') and states a hard prerequisite ('The phone must show video_live: true in list-phones-tool'). It never names phone-snapshot-tool explicitly, so the alternative is inferred rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds a real precondition beyond annotations: the phone must show 'video_live: true' in list-phones-tool, which prevents failed calls. It doesn't discuss output size or error behavior, keeping it just short of 5.

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

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

Three tight sentences with the core action front-loaded, followed by use context and then the precondition. No filler; every 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?

With no output schema, the description correctly states the output type (JPEG snapshot) and the key precondition. It is complete for a simple two-parameter read tool, though it could note the resolution default or failure mode more explicitly.

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 both the slot UUID format and the width range/default are already fully documented. The description's 'video_live: true' note reinforces the slot precondition but adds no new parameter mechanics, 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 ('Capture a JPEG snapshot of a farm phone screen') and distinguishes itself from phone-ocr-tool and phone-control-tool by defining its role as visual state inspection. An agent can immediately tell what this produces 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?

'Use it to see what is on screen before and after phone-control-tool input' gives a clear usage context and ties it to a specific sibling. It stops short of explicit when-not guidance or naming alternate inspection tools like phone-ocr-tool, but the intended workflow is unambiguous.

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

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

Annotations mark it non-read-only, non-destructive, non-open-world, but the description adds the crucial behavior the annotations cannot: the async approval flow, that 'applied: true' means an order was placed and funds held (not charged), and that a card decline orders nothing. This is substantial disclosure beyond 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?

It is a dense but front-loaded paragraph; the core action and the add/phones examples come first, followed by the approval and billing semantics. Every sentence carries load given the complexity, though the density makes it slightly heavy for one block of text.

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

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

With no output schema, the description still covers the full lifecycle an agent needs: the required terms acceptance, the approval/denial outcomes, the meaning of 'applied: true', the hold-vs-charge distinction, and the decline path. Nothing essential to correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds integration semantics that the schema lacks: that 'add: -2' drops two and 'phones: 5' is the target total, clarifying the either/or semantics and the negative-value convention in context of the billing effect.

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

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

The description opens with a specific verb+resource and scope: 'Change how many phones the rental covers,' immediately distinguishing it from an initial rental tool like start-rental-tool. Concrete examples ('add: 1', 'add: -2', 'phones: 5') make the exact action 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?

It states the normal flow (files the change, returns a link) and names the exact alternative to poll for the result: 'poll get-billing-request-tool for their answer.' It also spells out the exception path (standing allowance applied straight away) with the condition that selects it, plus the terms precondition.

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 the mutation/destructive profile, and the description goes well beyond them: it discloses asynchronous behavior (returns immediately as 'queued'), the polling contract, the failure/refusal semantics, and the special tiktok_warmup behavior (starts one session per phone, returns 'running' plus sessions/skipped_busy_slots). This is exactly the kind of behavior an agent cannot infer from the structured fields.

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

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

Front-loaded with the core action and the async/polling contract, and every sentence carries information. It is dense and the tiktok_warmup paragraph is long, but it is not padding – each clause adds a behavioral fact 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?

With no output schema, the description compensates by naming the returned fields (id, status, sessions, skipped_busy_slots, outcome, result, phone_reports) and the exact state machine to wait on. For a 3-param, open-world automation trigger this is complete enough to call and follow up 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 payload is ignored for tiktok_warmup automations, and ties automation_id/slots to their source tools (list-automations-tool, list-phones-tool). The slots-omit-to-run-all behavior is also reinforced in prose.

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 one of the user's automations now') and anchors it to the familiar web-app 'Run now' action. An agent can immediately distinguish it from run-macro-tool and run-phone-agent-tool because it is scoped to a user automation by automation_id.

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

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

Explicitly names the follow-up tool (get-automation-run-tool), the exact polling condition (until status is done, failed or stopped), and the fields to read afterwards. It also enumerates the refusal conditions (automation off, run in progress, daily limit, no phone online, agent unavailable), so the agent knows what a non-started response means.

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/open-world, but the description adds genuinely new behavioral context: the run can take minutes, it is queued and returns a run id immediately rather than blocking, and the agent must poll get-phone-run-tool until success or failure. That async contract is the key fact an agent needs and is not derivable from 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-loads what the tool does, then the precondition, then the two input modes as a compact bulleted either/or. Slightly dense but every sentence carries an operational constraint; the alternative-tool note is placed exactly where the ambiguity arises.

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

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

For a destructive, open-world, no-output-schema tool it covers the full loop: prerequisite state check, one-of input modes, async queue-and-poll return semantics, and the sibling to use for natural-language tasks. An agent has everything needed to call it and handle the result.

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 already 100%, so baseline is 3, but the description adds real meaning: slot must be the UUID not the display name, workflow must be a name from list-macros-tool, params fill {{placeholders}} and must be scalars, and steps are run as-is with each needing an action.

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+scope: 'Replay a recorded macro (or a raw step list) on one farm phone: exact taps, swipes and typing, with no AI deciding anything.' It explicitly differentiates itself from the sibling run-phone-agent-tool, so an agent can route without opening either schema.

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

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

Gives explicit when-to-use (recorded macro or raw step list), when-not (tasks described in words → run-phone-agent-tool), a precondition (phone must show video_live: true in list-phones-tool), and the mutual-exclusion rule for workflow vs steps. Nothing 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 destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so safety is covered. The description adds genuinely new behavior: the call is asynchronous and returns a run id immediately rather than the result, which the annotations do not convey. It does not spell out what on-phone state may be altered, so it stops short of a 5.

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

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

Three sentences, each earning its place: purpose first, task-shaping guidance with an example second, and the async/polling workflow third. No redundancy and the most important constraint is front-loaded.

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

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

For a two-parameter async dispatch tool with no output schema, the description supplies the remaining essentials: that the return value is a run id, how to retrieve the eventual result, and how to inspect the screen. An agent has everything needed to call it and act on the result.

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 both 'slot' (with its video_live precondition) and 'task' are already fully documented in the schema. The description reinforces the narrow-task expectation for the 'task' parameter but adds no format, syntax, or constraint beyond that, 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: dispatch an on-phone GUI agent for a narrow task on a farm phone. The scope qualifiers ('narrow task', 'on-phone GUI agent') distinguish it from phone-command-tool, phone-control-tool, and run-automation-tool without the agent needing to open 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?

Explicitly tells the caller to keep tasks specific with a concrete example, names the follow-up tool (get-phone-run-tool) and the condition for using it (poll until success/fail), and routes to phone-snapshot-tool for seeing the screen. When-to-use and how-to-follow-up are both pinned down.

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

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

Annotations only declare the read/create/destructive profile; the description goes well beyond them, disclosing that the link saves the card, holds one month per phone, that nothing is charged immediately, when the hold is actually charged (on assignment or admin confirmation), and that an admin must assign concrete phones. This is exactly the behavioral detail the annotations cannot convey.

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

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

Front-loaded with the core action and then ordered logically (charge model, parameter choice, legal prerequisite, follow-up). It is dense but every sentence carries information, with only minor duplication of the accept_terms wording already present in the schema.

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

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

With no output schema, the description carries the full burden and does so: it explains what the tool returns (a Checkout link), the post-call workflow, and how to observe results via get-billing-tool. An agent has everything needed to call this correctly and to tell the user what happens 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?

Schema description coverage is 100%, so the schema already documents the phones/items mutual exclusion, quantity bounds, and the ISO-2 country default. The description restates the either/or choice without adding syntax or edge-case detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource — 'Order phones by returning a Stripe Checkout link' — and immediately clarifies the transactional semantics (no charge at the link). An agent can distinguish this from sibling order tools like request-phones-tool and the submission/account tools without opening any schema.

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

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

Gives explicit context: choose `phones` (+ optional `country`) for one country or `items` to spread across several, plus the hard prerequisite of showing the terms/privacy URLs and obtaining agreement. It also names the follow-up (poll get-billing-tool). It does not, however, contrast itself with the similarly named sibling request-phones-tool, so the routing guidance is incomplete.

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

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

Annotations declare readOnlyHint=false, idempotentHint=true and destructiveHint=false; the description adds real value beyond that by disclosing partial-update semantics ('Only the supplied fields are changed'), the authorization requirement, and that platform is immutable here. It is consistent with the idempotent annotation but does not mention failure behavior or return shape.

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

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

Two tight sentences with the scope and platform set front-loaded and the update semantics immediately after. No filler or redundancy.

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 full annotation coverage, a complete schema and no output schema, the description supplies the key behavioral facts an agent needs: partial update, auth scope, and platform immutability. Only error/conflict behavior remains undocumented, a minor gap.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema, which sets the baseline at 3. The description adds only the 'platform cannot be changed here' constraint, which is not a parameter in the schema, so it contributes little parameter-level meaning.

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 ('Update') and resource ('posting account'), scoped to the platforms TikTok, Instagram and YouTube. The verb cleanly separates it from create/get/list/delete siblings, though no sibling is named to differentiate from other update-style 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?

The description implies usage context via 'the authenticated user is allowed to manage' and constrains editing to supplied fields only, but it never states when to prefer this tool over get-account-tool or create-account-tool, nor any explicit prerequisite or exclusion. Usage is inferable rather than stated.

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