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

The description goes well beyond the annotations, revealing a non-obvious behavioral trait: a successful answer starts a new continuation run, and the returned run_id belongs to that new run, not the parked one. It also discloses standing-consent side effects for always_allow and the soft-budget semantics for max_turn_seconds. These are material and not visible from the input schema or openWorldHint alone.

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

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

The description is a few dense sentences with no filler. The first sentence is an immediate purpose and the rest explains conditional behavior and the crucial continuation-run nuance. 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 moderate-to-complex tool with 7 parameters and no output schema, the description covers the important pitfalls: approval vs input, continuation run id, consent revocation, and soft budget semantics. It could still mention error/edge cases or example usage, but given the excellent parameter descriptions in the schema, it is sufficiently complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds useful cross-parameter semantics: approved=true/false for approvals, value for input requests, and clarification that run_id is the currently parked run. It further clarifies always_allow requires approved=true and is only valid on consent_tool rows. This goes beyond the schema but is not overwhelming.

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 clearly states the tool's core actions: 'Answer a run that is paused on a human-input request', distinguishes between approval and input, and references list_pending_inputs as the source of pending requests. It also stands apart from siblings list_pending_inputs and the later poll through get_run_result.

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 guidance is present: use this after finding a pending request via list_pending_inputs, and poll the returned continuation run with get_run_result. The description also clearly separates approval vs input data via approved/value. It does not explicitly say when not to use or which sibling would be an alternative, but it is inferable and the sibling references give enough 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?

Beyond the destructiveHint annotation, the description discloses the asynchronous nature of cancellation, the immediate return status of 'cancelling', the need to poll get_run_result for the final 'cancelled' state, and the limitation that finished runs cannot be cancelled. These are important behavioral traits not present in the annotations.

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

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

Three sentences, with the core purpose in the first sentence and supplementary workflow details following. Every sentence contributes meaningful information with no redundancy or filler.

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

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

Despite having no output schema, the description compensates by explicitly stating the immediate return status ('cancelling') and the subsequent polling step to reach the final state. The tool's contract is fully described for the agent, including the edge case of finished runs.

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 input schema already provides 100% coverage for both parameters (run_id and agent_id), including a note that run_id is from invoke_agent. The description adds no additional semantic meaning or usage detail about the parameters themselves, so the baseline of 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?

The description opens with 'Stop an in-flight agent run', which is a specific verb+resource statement that clearly denotes cancellation of an active run. It distinguishes itself from sibling tools like get_run_result (which polls status) and delete_agent (which deletes an agent) by focusing on the run lifecycle.

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 explicitly states when to use the tool (for in-flight runs) and when not to (for runs that already finished). It also provides an explicit workflow: call cancel_run, then poll get_run_result until status becomes 'cancelled'. This is clear directional guidance with a named alternative for monitoring.

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?

Beyond the annotations (idempotentHint), the description discloses idempotent behavior (returns existing agent if name exists) and notes that the model parameter is ignored when reusing an existing agent. It also mentions account plan limits for creation, adding significant behavioral context not present in annotations.

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

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

The description is concise yet comprehensive, with each sentence serving a purpose. It covers purpose, usage context, idempotency, and limitations without redundancy, maintaining clear logical flow.

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?

Given only two parameters and no output schema, the description covers all essential aspects: core function, illustrative use cases, anti-cases, behavior on reconnection, and plan constraints. It is fully self-contained for an agent to decide and invoke 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?

Although the schema already describes both parameters, the description adds crucial nuances: for 'model', it explains the default routing behavior (cheapest fitting model) and the paid-plan requirement for frontier models. This enriches the schema and clarifies practical usage.

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 clearly states the tool's purpose as 'Get or create an agent by name' and distinguishes it from sibling get_agent/list_agents by emphasizing the create-or-reuse behavior. It explicitly mentions persistent environment and the right way to reconnect, making it 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?

The description provides explicit guidance on when to use (long-term projects, accumulating files) and when not to use (one-off scripts), plus highlights it as the correct method for reconnecting to an existing agent. This fully equips an agent to choose this tool appropriately over alternatives.

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

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

Annotations provide only openWorldHint=false and destructiveHint=false, so description carries the burden. It adds key behavioral details: new workflow has no steps and cannot run yet, trigger defaults and preconditions, agent_id ownership semantics, and webhook hook URL generation. No contradiction with annotations.

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

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

The description is moderately long but every sentence serves purpose, lifecycle, or parameter clarification. It is front-loaded with the main action and logically progresses through creation, limitations, and next steps. No redundant phrases, though slightly dense.

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

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

Given no output schema and sparse annotations, the description gives a complete picture of the tool's behavior: return value (id, hook URL), default trigger, inability to run until steps built, and how to proceed (invoke_agent, run_workflow). It could mention error behavior or permissions, but overall very thorough for a create 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 covers 100% of parameters, but description adds interdependent meaning beyond schema: trigger_kind default and cron_expr requirement, webhook hook URL generation, and agent_id ownership/assignment behavior. This goes beyond simple field descriptions, adding relationship and side-effect context.

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

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

The description states a specific action ('Create an empty workflow') and result ('Returns the new workflow, including its id and — for a webhook trigger — its hook URL'). It clearly distinguishes from siblings like run_workflow (run existing) and get_workflow (fetch), focusing on creation and the empty initial state.

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

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

Provides an explicit lifecycle: create → build steps with invoke_agent (sibling tool) → run with run_workflow. Also explains trigger_kind options and requirements (manual default, cron needs cron_expr, webhook mints public URL), clearly indicating when to use this tool and what to do next.

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, but the description adds 'revoke its disk' and 'cannot be undone', providing extra behavioral context about what exactly gets destroyed and the permanence. This adds value beyond the annotation alone.

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

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

Two sentences, front-loaded with action and consequence. No wasted words. Efficiently conveys the core purpose and key warning.

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

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

For a simple one-parameter delete tool with annotations, the description is completely sufficient. It covers the agent_id parameter, the destructive nature, and the irreversibility. No output schema needed.

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 parameter description is sufficient ('The agent's UUID to delete.'). The description adds no additional meaning beyond what the schema already provides, so baseline score of 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 clearly states the tool's purpose: permanently delete an agent and revoke its disk. It uses a specific verb ('delete') and resource ('agent'), and the irreversibility is emphasized. Differentiates from sibling tools like create_agent, get_agent, etc.

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

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

No explicit guidance on when to use this tool versus alternatives. Lacks context like 'only if agent is no longer needed' or warnings about irreversibility beyond the description. Sibling tools are listed but no comparative advice.

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?

Beyond the annotations (idempotent, non-destructive), the description adds crucial behavioral details: edits are applied as a new draft version, a stale base_version is rejected instead of overwriting concurrent work, and editing does not activate the draft. These disclosures help the agent understand side effects and concurrency semantics, exceeding what annotations alone provide.

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

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

The description is two sentences long, front-loaded with the core action and purpose, and includes only essential usage and behavioral caveats. No redundant wording or filler; each clause adds necessary 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 moderately complex tool with no output schema, the description covers the primary behaviors: batch edits, new draft version, compare-and-swap, prerequisite read, concurrency protection, and non-activation. It does not mention the return shape (e.g., new version number) but that is a minor omission given the tool's function and available annotations.

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

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

Schema description coverage is 100%, so all three parameters are already well-documented. The description adds little beyond what the schema provides, only implicitly referencing base_version compare-and-swap (already in schema) and listing supported ops (already in the enum). It does not compensate for any schema gaps because there are none.

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 clearly states the tool applies a batch of constrained edits as a new draft version using compare-and-swap. It specifies the supported operation types (set_params, add_step, remove_step, add_router) and contrasts with sibling tools like create_workflow and run_workflow by emphasizing the batch edit and draft version behavior.

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 explicitly instructs reading the current workflow version with get_workflow_version first and warns that a stale base_version is rejected, providing clear context for correct usage. It does not name alternative tools for cases like creating a new workflow, but the prerequisite and the 'does not activate the draft' note offer strong usage 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?

The readOnlyHint annotation already indicates a safe read operation. The description adds the specific fields returned (name, type, model, status), which gives some insight into the response, but it does not disclose error handling, response shape, or other behavioral traits. This is consistent with the calibration example for get_calls, which received a 3 for similar incremental transparency.

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

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

The description is a single compact sentence that immediately states the verb and resource, then provides relevant detail. Every word contributes to clarity, with no filler or repetition.

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 read-only retrieval tool with one parameter and no output schema, the description adequately conveys purpose and response fields. It does not mention error cases or edge behaviors, but the simplicity of the tool and the readOnlyHint annotation make this a minor omission. The completeness is slightly better than minimal due to the explicit field list.

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 description coverage is 100% for the single parameter agent_id, and its description already explains it's a UUID from list_agents or create_agent. The tool description merely paraphrases 'by its id' without adding new semantic meaning, so the baseline of 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 clearly states the action ('Get') and the resource ('one agent's details') while specifying the included fields (name, type, model, status). It distinguishes from sibling tools like list_agents (which lists all agents) and get_workflow (which gets workflow details), making the purpose 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?

The description implies usage by stating 'Get one agent's details by its id', and the parameter description notes where to obtain the id (list_agents or create_agent). However, it does not explicitly state when to use this tool over alternatives or provide exclusions, leaving the guidance at an implied level.

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

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

The readOnlyHint annotation confirms this is a safe read operation. The description adds behavioral context beyond the annotation by noting that running agents spends the balance, making the account state relevant to subsequent actions. It does not contradict the annotations.

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

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

The description is only three sentences, all of which carry useful information: purpose, usage context, and an explicit alternative plus output format clarification. It is front-loaded and free of filler.

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

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

For a zero-parameter, read-only balance tool, the description is complete: it states what is returned, when to invoke it, and how it relates to other tools. No significant information gaps remain.

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

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

There are zero parameters, so the schema imposes no burden and the baseline is 4. The description adds extra meaning by explaining the balance_usd output format, which is useful, though not strictly parameter-related.

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 clearly identifies the tool's purpose: retrieving the authenticated account's US-dollar balance and plan. It uses a specific verb and resource, and distinguishes itself from get_usage by explicitly noting that get_usage is for where money went.

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 provides clear usage guidance, stating that agents spend this prepaid balance and that users should check it before invoking agents. It also explicitly directs users to get_usage for expense details, offering a concrete alternative.

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, so the description adds value by specifying the exact returned data fields (bytes and cost). No contradictions or missing behavior.

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

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

One short sentence conveying essential information with zero waste. Front-loaded with verb and resource.

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?

Given zero parameters, simple output, and annotations covering read-only nature, the description fully specifies what the tool returns, making 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?

No parameters exist, so baseline is 4. The description adds no parameter info but explains the return data, which is sufficient.

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 specifies the verb 'Get' and resource 'disk state' with clear data fields (included, purchased, used bytes, monthly cost). It distinguishes from sibling tools which focus on agents, workflows, credits, etc.

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

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

No explicit when/when-not or alternative guidance is provided. However, the tool's simple read functionality and lack of overlapping siblings make usage context implied.

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

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

The description adds substantial behavioral context beyond the readOnlyHint annotation: it explains credit/token counter behavior, liveness interpretation, failure details (cause and retryability), and inline inclusion of pending request details. This is rich, non-obvious information that helps the agent understand side effects and edge cases.

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

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

The description is a single, well-structured paragraph that front-loads the primary purpose and then adds essential operational details. Every sentence contributes value, and the length is justified given the tool's complexity; 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?

No output schema exists, but the description fully explains the return payload (status, timestamps, credits/tokens, reply, URL, failure info, awaiting_input details) and how to interpret it. It also covers liveness checking and normal conditions, making it complete for the tool's use case.

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 parameter descriptions in the schema already explain agent_id and run_id. The tool description adds minimal extra meaning—it notes run_id is 'returned by invoke_agent,' which is already in the schema. 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?

The description clearly specifies the tool's function: retrieving a run's status, timestamps, credits/tokens, reply, and URL. It uses specific verbs ('Get', 'poll') and resource ('run') and distinguishes itself from related tools by referencing invoke_agent and answer_pending_input.

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 guidance is provided: 'Use to poll a run started with invoke_agent wait=false.' It also explains how to judge liveness via last_heartbeat_at and mentions the awaiting_input status in relation to answer_pending_input, giving clear context for when to use this 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, and the description adds substantive behavioral context by detailing what the usage rollup contains (spend by meter/agent, recent runs). It does not contradict annotations and provides useful information about the return content, though it does not mention exact time ranges or pagination.

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

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

The description is two concise sentences: the first states the tool's purpose, the second provides usage guidance. Every word contributes value, and it is front-loaded with the core action. Perfect conciseness.

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 read-only tool with no parameters and no output schema, the description fully covers what the tool does, what it returns, and how it differs from related tools. It is sufficient for an agent to select and invoke it correctly without ambiguity.

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 has zero parameters, so the baseline is 4. The description adds meaning by describing what the resource represents (usage rollup) without needing parameter explanations. Since the schema carries no parameter info, the description effectively communicates the tool's scope.

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 clearly states the tool's function: retrieving the authenticated account's usage rollup with specific details (US-dollar spend by meter and agent, recent runs). It also distinguishes itself from the sibling get_credits, making the purpose 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?

The description explicitly states when to use this tool ('to answer where the money went') and explicitly directs to get_credits for current balance. This provides strong usage context and an alternative, fully satisfying this dimension.

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, so the read-only nature is covered. The description adds valuable behavioral context by explaining the projection version selection: active_version for pinned execution, falling back to current_version for drafts. This nuance is not present in annotations and helps the agent understand which version is returned.

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

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

The description is two sentences with an effective front-loaded structure: the first sentence states the core purpose, and the second explains a key behavioral detail. No redundant or unnecessary 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?

This is a simple read-only getter with one parameter and no output schema. The description fully addresses the tool's purpose and the only non-obvious behavior (projection version). No significant gaps remain for an agent to invoke 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% with a clear description for workflow_id ('The workflow's UUID (from list_workflows or create_workflow)'). The tool description adds no additional parameter semantics beyond what the schema provides, so the baseline of 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?

Clear verb+resource: 'Get one workflow's metadata and step projection'. This distinguishes from sibling tools such as list_workflows (which lists all workflows) and get_workflow_execution (which retrieves execution details) by focusing on a single workflow's metadata and step projection.

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 by stating what the tool returns, but it does not explicitly contrast with alternatives like get_workflow_execution or list_workflows, nor does it state when not to use this tool. The schema mention of list_workflows/create_workflow for obtaining the ID provides some context, but no direct when-to-use 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 openWorldHint=false, and the description adds context by specifying the returned data (status, timing, credits, full payloads) and that it reads from 'persisted execution.' It implies safe repeated polling, but doesn't elaborate on error behavior or rate limits; still adds value 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?

Two sentences, front-loaded with the core function and payload details, followed by practical usage guidance. No redundant or filler content; 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?

Given the tool's simplicity (two parameters, no output schema), the description fully covers what it does, what it returns, and when to use it. It even highlights the sibling omission, making the context complete for an agent deciding between list and get operations.

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 both parameters, with each already described. The description adds minor context (e.g., 'from run_workflow' for execution_id), but largely relies on schema descriptions, so the baseline score of 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?

The description uses a specific verb 'Get' with a precise resource ('one workflow execution's status, timing, credits, and full per-step input/output payloads'). It distinguishes itself from sibling list_workflow_executions by explicitly noting that list omits step payloads, making its purpose unique.

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 guidance is provided: 'Use to poll a run started with run_workflow or inspect what each step returned.' It also contrasts with the alternative by stating 'list_workflow_executions deliberately omits step payloads,' giving clear when-to-use/when-not-to-use direction.

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, so the agent knows this is a safe read. The description adds behavioral context by specifying that the response includes both the full builder definition and a value-light projection, which is useful for understanding what the tool returns. No contradictions with 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?

Two concise sentences: the first states the tool's purpose and content, the second gives clear usage guidance. Every word earns its place, with no redundancy 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?

For a simple, read-only get operation with two fully documented parameters and clear annotations, the description covers the essential context: return content, the distinction from get_workflow, and when to use it. The absence of an output schema is mitigated by the description's mention of the two projections.

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 workflow_id and version clearly described in the input schema. The description adds minimal parameter-specific meaning beyond what the schema provides, so the baseline score of 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?

The description uses a specific verb ('Get') with a clearly defined resource ('one exact workflow version') and lists what's included ('full builder definition with step parameter values and its value-light projection'). It also distinguishes this from the sibling get_workflow by referencing 'current_version', making its purpose 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?

The second sentence gives explicit when-to-use guidance: 'Use current_version from get_workflow unless you intentionally need an older version.' This directly names an alternative tool and provides a clear decision rule, which is exactly what usage guidelines should do.

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?

Beyond annotations (openWorldHint=true, destructiveHint=false), the description discloses many behavioral traits: it blocks the caller's turn, waits up to ~25s, may return a running status with run_id, bills credits, enforces in-flight caps (429), does not queue turns, handles human-input pauses with awaiting_input, and returns a session URL. There is no contradiction with 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?

Though long, every sentence earns its place. The description front-loads the purpose and then systematically covers usage rules, blocking behavior, billing, retries, human input, and result contents. No redundancy or filler; the density is justified by the tool's complexity.

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 full responsibility for return values—it explains the reply, run_id with status 'running', awaiting_input details, and a URL. It also covers error conditions (429), side effects (credits, billing), and integration with sibling tools (poll via get_run_result, respond via answer_pending_input). For a tool with 7 params and complex async behavior, this is 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?

The schema has 100% coverage for all 7 parameters, so the baseline is 3. The description adds meaningful context for wait (explains blocking and no backgrounding, when to switch to wait=false), idempotency_key (retry scenario and billing avoidance), and session_id (carried from previous results). This extra guidance raises the score above baseline.

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 a message to an agent and get its reply,' which clearly defines the tool's core purpose. It also distinguishes from sibling tools by explicitly mentioning get_run_result and answer_pending_input as related operations, and contrasts invoke_agent with 'a plain code sandbox' for stateless work.

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

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

Provides explicit when-to-use guidance ('work that should outlive a single request'), when-not-to-use ('stateless snippet... plain code sandbox is cheaper'), and when to set wait=false for long turns. Also explains when to use idempotency_key for retries and references get_run_result and answer_pending_input for follow-up, giving clear alternatives.

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

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

Consistent with readOnlyHint=true. Adds context about returning model and live session status, which annotations don't specify. No contradiction.

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

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

Single, front-loaded sentence with no redundancy. Every word adds value.

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?

Provides key return details (model, live session status) despite no output schema. Lacks info on pagination or ordering, but adequate for simple 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?

No parameters; schema coverage 100%. Baseline score of 4 applies as description adds no parameter info, which 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?

Clearly states it lists agents owned by the authenticated account, including model and live session status. Different from sibling tools like create_agent or delete_agent.

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?

Implicitly limited to owned agents, but no explicit guidance on when to use vs alternatives like list_workflows or when not to use.

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

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

The description expands on the readOnlyHint by explaining lazy token refresh, the meaning of past expires_at, null as never-expiring, and that token material is never returned. These behaviors are not implied by the annotation and are essential for correct interpretation.

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: the primary function, the status field's meaning, and token refresh/security details. Front-loaded with the main action and no filler.

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

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

For a parameterless read-only list tool with no output schema, the description fully covers what the agent needs: the resource, the fields returned, how to interpret status and timestamps, and security guarantees. The lack of an output schema does not create a gap because the description narrates the key return semantics.

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 has zero parameters, so the schema already fully covers this dimension (100% coverage trivially). The description adds meaning about the response semantics, which is valuable given there are no parameters to explain. Baseline 4 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?

The description states a specific verb and resource ('List the authenticated account's third-party OAuth connections') and details what it returns (status, auth/expiry times, scopes). This clearly distinguishes it from sibling tools focused on agents, workflows, and runs.

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 for checking connection health via the status predicate ('authorized needs no action; reconnect_needed or unauthorized does'), which is a clear use case. No explicit alternative is given, but no sibling tool serves this purpose, so context is sufficient.

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, so the safe-read nature is covered. The description adds valuable behavioral nuance: it explains that rows with a 'consent_tool' are write-consent approvals and that answering with always_allow=true stops future prompts for that tool. This goes beyond the structured annotations.

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

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

The description is two sentences long, front-loaded with the core purpose, and then adds one crucial clarification about consent_tool behavior. No filler or redundant repetition of the title or schema.

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

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

For a simple list tool with one parameter and no output schema, the description covers the essential behavior and the special consent_tool semantics. It doesn't mention return format or pagination, but the tool is straightforward and the provided context is sufficient for most use cases.

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

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

Schema coverage for the single parameter (agent_id) is 100%, so the schema already documents it. The description doesn't add any additional param-specific details, but with full schema coverage the baseline score of 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?

The description opens with a specific verb and resource: 'List the agent's runs that are paused awaiting a human approval or input (the HITL queue).' This clearly distinguishes the tool from siblings like list_runs by focusing on pending approvals. The term 'HITL queue' adds precision.

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

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

The description implies when to use the tool—when you need to see the HITL queue—and provides context about consent_tool rows. It doesn't explicitly contrast with alternative tools like list_runs or answer_pending_input, but the context is clear enough for an agent to infer appropriate usage.

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, so the read-only nature is covered. The description adds the ordering (most recent first) and that each run's status is included, which is useful behavioral context. It does not disclose pagination or response format, but the bar is lower due to 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?

One sentence, front-loaded with the verb and resource, no redundant words. It is appropriately concise.

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?

Given the low complexity (one parameter, read-only, no output schema), the description is mostly complete: it states the purpose, ordering, and status inclusion. It could mention pagination or limits, but for a simple list tool it is adequate.

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 input schema fully documents the single agent_id parameter with a clear description, so baseline is 3. The tool description adds no parameter-specific information beyond that.

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 clearly states the tool lists an agent's run history, with ordering (most recent first) and status detail. However, it does not explicitly differentiate from sibling tools like list_workflow_executions or get_run_result, so it lacks sibling distinction.

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 provides no guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. It implies usage only through its name and description, which is insufficient given the large sibling set.

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 the description adds valuable context about ordering (most recent first) and the types of data returned (status, fault, trigger source, timing, credits, timestamps). This goes beyond the annotations and helps set expectations.

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

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

The description is a single, well-structured sentence that front-loads the core action and includes essential details without any fluff.

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 helpfully enumerates the fields returned (status, fault, etc.) and specifies ordering. It is sufficiently complete for a simple list operation, though it does not mention pagination limits.

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% for the single parameter, with a clear description in the schema ('The workflow's UUID'). The tool description does not add extra parameter semantics, so it stays at the baseline.

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 clearly states the tool lists a workflow's recent executions, with specific details on ordering (most recent first) and included fields. It distinguishes itself from siblings like get_workflow_execution (which fetches a single execution) and list_runs (which lists runs generally) by scoping to a workflow's executions.

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 provides clear context by specifying 'a workflow's' executions, indicating it is for workflow-scoped queries. However, it does not explicitly mention alternatives or when not to use it, though the context strongly implies it is for recent execution history.

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 indicate read-only behavior. The description adds useful behavioral context by stating the returned fields (status, trigger, current version, agent_id) and the ownership constraint (only the owning agent can edit/run). This goes beyond the annotation but does not disclose potential limitations like pagination or ordering.

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

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

The description is three sentences with the primary purpose front-loaded. Every sentence provides relevant information without redundancy, making it concise yet comprehensive.

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 read-only list tool with one optional parameter and no output schema, the description covers purpose, returned fields, filtering options, and the ownership concept. This is sufficient for an agent to understand what to expect and when to use it.

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 already documents the agent_id parameter with full coverage. The description adds value by explaining the semantics of 'none' (unassigned workflows created here or in the web app) and reinforcing that the parameter is optional, thereby enhancing the schema's 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?

The description clearly states the tool lists workflows owned by the authenticated account, specifies the returned fields (status, trigger, version, agent_id), and distinguishes itself from sibling tools like get_workflow (single item) and create_workflow (creation). The verb 'list' is specific to the resource and scope.

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 provides clear context on when to use the tool: to list workflows owned by the account, with filtering by agent_id. It also explains the 'none' option for unassigned workflows. However, it does not explicitly mention alternatives or when not to use this tool relative to siblings like get_workflow or list_workflow_executions.

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

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

The description discloses real side effects, billing details (1 credit + model usage), the short wait and terminal/running return, and the requirement of pre-built steps. This goes well beyond the annotations (openWorldHint=true, destructiveHint=false) and provides actionable behavioral expectations.

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 deliver the main action, billing, return behavior, polling instruction, and prerequisite. Every sentence earns its place; the description is front-loaded with the most important information and contains no filler.

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

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

Despite having no output schema, the description explains what the return contains (terminal if finished, status 'running' otherwise) and how to proceed. It also covers prerequisites and alternatives, making the tool fully usable from the description alone.

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?

Both parameters are fully described in the input schema (100% coverage), and the description adds no additional parameter-level detail. The baseline of 3 applies; the schema carries the semantic weight.

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 'Run a workflow now', clearly stating the action and resource. It distinguishes from siblings by emphasizing immediate execution (vs schedule_run), mentions polling with get_workflow_execution, and references invoke_agent for the prerequisite, making its purpose 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?

The description provides clear context for when to use it: 'now' implies immediate execution as opposed to scheduling, and it explicitly names invoke_agent for missing steps and get_workflow_execution for polling. It stops short of explicitly contrasting with schedule_run for future runs, but the guidance is strong.

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 include openWorldHint=true and destructiveHint=false, but the description adds valuable behavior: 'billed like any run' (cost), 'appears in list_runs when it fires' (observability), and 'invoked once, later' (timing). This goes beyond the annotations, though it doesn't mention cancellation or auth.

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 purpose, followed by timing options and the alternative for recurring schedules. No fluff, every sentence serves a purpose.

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

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

The description covers the tool's role, behavior, billing, visibility in list_runs, and the alternative tool for recurring schedules. With 5 parameters fully described in schema and no output schema required, this is complete for an agent to select and invoke the tool 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%, with each parameter already described in the schema. The description reinforces the mutual exclusivity of delay_seconds and fire_at, but does not add new parameter-specific information 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?

The description clearly states 'Schedule a ONE-SHOT deferred run of an agent' with specific verbs and resource, and distinguishes itself from create_workflow by emphasizing one-shot vs recurring. It also explains the run will appear in list_runs, adding further clarity.

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 explicitly says 'For a recurring schedule, use create_workflow with a cron trigger instead,' providing a direct alternative. The context of when to use (deferred one-shot) is clear, and it indicates the choice between delay_seconds and fire_at.

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=false and idempotentHint=true. The description adds behavioral context beyond this: the change takes effect on the agent's next turn, and explicit frontier models require a paid plan. No contradiction with 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?

Two front-loaded sentences convey purpose, timing, and constraints with zero redundancy. Every sentence earns its place, and the description avoids repeating schema details.

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 2-parameter tool with strong annotations and full schema coverage, the description is complete. It covers what the tool does, when the effect occurs, and important plan restrictions. No output schema is needed for a setter.

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 parameters documented. The description adds value by explaining the plan-scaled Auto default and the paid-plan requirement for explicit frontier models, enriching the model parameter semantics 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?

The description opens with 'Change an agent's model' – a specific verb and resource that clearly distinguishes this from sibling tools like create_agent, invoke_agent, or delete_agent. It unambiguously states the tool's purpose.

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 provides useful context for when to use it: it applies to existing agents and takes effect on the next turn. The note about Auto (plan-scaled) and paid frontier models gives usage constraints. It does not explicitly name alternatives, but the context is clear enough.

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