Ephemeral

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnly=false, so the safety profile is covered. The description adds genuine non-annotation context: partial work is still billed, and cancelling a finished run changes nothing (consistent with the idempotent hint). It omits any auth/permission requirements or rate limits.

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

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

Three short sentences, front-loaded with the core action and precondition, followed by the two consequential facts. No filler and nothing repeated from the title or annotations.

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

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

For a single-parameter mutation with full annotation coverage, the definition covers the essential behavior including side effects. The only gap is that no output schema exists and the description does not say what is returned on success versus on a no-op cancel.

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 coverage is 100%, with the schema describing the id as 'as returned by create_run'. The description adds nothing beyond that, so the baseline 3 applies – the schema does the work.

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

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

States a specific verb (cancel) plus the resource (run) and adds a state precondition ('that has not finished'), which distinguishes it from read-only siblings like get_run, list_runs and wait_for_run. An agent knows exactly which operation this performs without opening the schema.

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

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

Gives clear usage context: use on runs that have not finished, and notes that calling it on a finished run is a harmless no-op. It does not name an alternative tool or state prerequisites (e.g., permissions), so it falls short of full when/when-not/alternatives 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?

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false): it discloses billing destination (organization of the API key), cost cap and timeout enforcement, provisional vs. final cost semantics, hosted-service pricing components, and retry safety via idempotency_key. That is exactly the operational context an agent needs before incurring spend.

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 purpose and control-flow guidance in the first two sentences, with cost/pricing detail after — a good ordering. The trailing pricing sentence is dense and slightly sprawling, but it earns its place for cost-capped runs.

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 15-parameter, nested-object creation tool with no output schema, the description covers the return shape (queued run), asynchronous result retrieval, cost finality, prerequisites, and billing — nothing needed 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 coverage is 100%, so the baseline is 3; the description adds real semantic value by explaining max_cost_micros' role as a hard stop, idempotency_key's retry behavior, and that connections must pre-exist and are referenced by name. It stops short of explaining zero_data_retention, files, or web scoping in the description, leaving those to 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+resource ("Start an AI agent run in an isolated sandbox") plus immediate return state ("status queued"), which distinguishes it from get_run/wait_for_run and from schedule/run_schedule siblings referenced in the text.

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 two usage modes ("Give a prompt, or the name of a saved workflow") and routes follow-up work to alternatives: "Poll with get_run or block with wait_for_run for the result." It also states the connections prerequisite (must already be saved, reference by name) and when to use idempotency_key.

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 say non-read-only, non-destructive, and non-idempotent. The description adds substantial context beyond that: admin-key authorization, billing to the organization on each start, cost-cap defaulting, self-pausing after repeated failed starts, and a 50-schedule per-organization quota. These are exactly the operational facts an agent cannot infer from 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?

Five short sentences with zero filler, and the core action is stated first, followed by prerequisites, cost implications, and limits. Every sentence carries an operational fact that affects whether or how to call 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?

For an 8-parameter creation tool with no output schema and no annotations covering cost or quota, the description covers permissions, billing, limits, and lifecycle. The one gap is the return value: an agent is not told that the created schedule yields an identifier needed by get_schedule, update_schedule, or delete_schedule.

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; the description adds genuine semantics beyond the schema by noting that max_cost_micros falls back to a default when omitted and that the cost is billed per start. It does not clarify the cron/input interaction further, but the one concrete addition justifies going 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 opening sentence gives a precise verb and resource combination: creates a schedule that starts a saved workflow on a timetable. This implicitly separates it from the immediate-run sibling create_run and from preview_schedule. However, the differentiation is only implicit; it never explicitly says 'not create_run', so it falls just short of the top score.

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 preview_schedule first to check the timetable' names an alternative tool and the condition that should select it, and 'Needs an administrator key' states a prerequisite. There is no explicit statement of when not to use this tool (for example, use update_schedule for changes, or create_run for an immediate one-off), which keeps it below a 5.

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

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

Annotations already flag destructiveHint=true, so the description does not waste words on that; instead it adds genuinely new behavior context: an administrator key is required, and already-running executions are unaffected by the deletion. That scoping of side effects is exactly what an agent needs before an irreversible call, and it is consistent with 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 short sentences, each load-bearing: the action, the authorization/scope caveats, then the safer alternative. The most important fact (permanence) 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 one-parameter destructive tool with rich annotations and no output schema, nothing needed is missing: permanence, auth requirement, blast radius, and the safer alternative are all covered. Return-value behavior is irrelevant here since a delete needs no output contract.

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 at 100% schema description coverage (id, format sch_…, sourced from create_schedule/list_schedules), the schema already carries the parameter meaning in full. The description adds nothing further about the id, 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?

"Permanently delete a schedule" gives a specific verb, resource, and irreversibility qualifier. It cleanly separates this tool from sibling mutations like update_schedule, create_schedule, and run_schedule.

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 routes the agent away from this tool when the intent is temporary: "To stop it for a while, pause it with update_schedule instead." That names the alternative and the condition that selects it, so the highest-value when-not guidance is present.

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 known; the description still earns credit by disclosing blast radius beyond the annotations: in-flight runs are untouched while dependent schedules are broken until the workflow is re-saved. It stops short of stating auth requirements or whether a missing name errors versus no-ops.

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 padding, with the destructive nature front-loaded and the consequence detail immediately after. Every clause carries information an agent needs before calling.

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

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

No output schema exists, and the description does not say what a successful call returns or how a nonexistent workflow is handled. Otherwise, for a one-parameter destructive tool whose annotations already flag destructiveness, the side-effect disclosure makes it callable without further reading.

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?

Single required 'name' parameter at 100% schema description coverage, so the schema already carries the semantics. The description adds nothing about the parameter (e.g., whether name is case-sensitive or accepts an ID), which is acceptable at this coverage level but not additive.

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?

Names a specific verb and resource ('Permanently delete a saved workflow') and is trivially distinguishable from the sibling delete_schedule by resource type. The adverb 'permanently' also signals this is not a soft-delete or archive operation.

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

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

Usage is only implied: the stated consequences (schedules stop starting runs) let an agent infer this is the right call when retiring a workflow, but there is no explicit when-to-use/when-not guidance and no named alternative (e.g., save_workflow to overwrite, or disabling a schedule).

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

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

Goes well beyond the readOnly/idempotent annotations: it explains that cost_micros is provisional while billing_pending, that results carry cost_final/cost_note, and — critically — that for a zero-data-retention run the first read of a finished run returns the output and then deletes it, a one-shot side effect an agent could not infer from destructiveHint=false. This is exactly the kind of context annotations cannot carry.

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 cost caveat is front-loaded and the zero-data-retention warning follows logically; most sentences earn their place. The closing sentence on run fees, per-second compute and provider pricing is somewhat tangential for a read tool and largely defers to GET /v1/me anyway.

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 must describe the return shape — and it does, naming status, output, error, cost_micros, billing_pending, cost_final and cost_note. Combined with the single fully-documented parameter and safe-read annotations, 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?

There is a single id parameter at 100% schema coverage, and the description adds no meaning beyond it (no format, prefix, or provenance detail not already in the schema). With the schema doing the work, 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?

Opens with a specific verb+resource and enumerates exactly what is returned: status, output, error, cost, billing_pending. It is clearly distinguishable from list_runs, though it never names the obvious sibling wait_for_run, which an agent might otherwise prefer over re-polling.

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 concrete when-to-act guidance for the cost field: quote only when cost_final is true, otherwise re-call get_run in a few seconds. It does not, however, tell the agent when to use this versus wait_for_run for a run that is still going, leaving the main alternative unaddressed.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered without the description. The only added value is describing the returned content, which is useful but is a return-shape disclosure rather than behavioral context such as error conditions or behavior when the schedule has never started.

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 no filler. Every clause earns its place by naming a field the caller will receive, which is valuable given there is no output 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 read-only single-record fetch with one fully documented parameter, the description covers the important gap left by the absence of an output schema by listing the return fields. What remains missing is minor: behavior for a non-existent id or a schedule that has never run.

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 a single required parameter and schema description coverage is 100%; the schema already explains that id is the sch_… value from create_schedule or list_schedules. The description adds no further semantics about the id, 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 uses a specific verb (Read) and resource (a schedule) and enumerates exactly what the response contains: timetable, time zone, input, cost cap, enabled flag, next start, and last start outcome. This clearly distinguishes it from mutation siblings like update_schedule or delete_schedule, though it never names another tool explicitly.

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

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

The singular 'Read a schedule' implies fetching one record by id rather than listing, which loosely separates it from list_schedules. However, the description gives no explicit when-to-use guidance, no mention of how to obtain the id, and no exclusions relative to get_run or preview_schedule; that information only appears inside the schema's id description.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new context beyond them: exactly which fields are returned and the explicit guarantee that credentials are never included, which matters for handling sensitive data. It stops short of describing behavior for a missing or unnamed workflow.

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: action first, contents second, security guarantee last. Every clause carries information and nothing is repeated from the title or schema.

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

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

With no output schema, the description usefully enumerates the returned fields (description, prompt, model, files, connections, limits, input_schema, output_schema) plus the credentials exclusion, which is enough to decide whether a follow-up call is needed. It omits error/not-found behavior for an unknown name, a minor gap for an otherwise simple read 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% for the single `name` parameter, so the schema already documents it fully. The description's phrase "saved workflow's definition" reinforces that the name identifies an existing workflow, but adds no format, casing, or lookup-resolution 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 ("Read a saved workflow's definition") and enumerates the fields returned, so the agent knows this is the full-record fetch rather than a listing. It implicitly contrasts with list_workflows, but never names that sibling explicitly, so differentiation is inferential rather than stated.

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

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

Usage is only implied: "Read a saved workflow's definition" suggests looking up a single known workflow by name, but there is no explicit when-to-use, when-not-to-use, or alternative (e.g. list_workflows to find a name first). No prerequisites are mentioned.

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

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

With annotations already covering readOnly, idempotent, and non-destructive behavior, the description adds valuable transparency: 'No URLs or secrets are returned' and the inclusion of connection type, methods, and tools. It does not describe pagination or ordering, but that is a minor gap given 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 short sentences, each earning its place: what the tool returns, what is excluded for security, and how to use the output in create_run. The information is front-loaded and waste-free.

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 annotations covering safety, the description provides enough context: it explains return fields and a security exclusion, and ties output to create_run. It could mention whether all connections are returned or any ordering, but the core behavior is covered.

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 parameter semantics baseline is 4. The description does not need to explain parameters, and it correctly avoids unnecessary detail.

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 resource (the organization's saved connections a run may use) and includes the returned fields (type, allowed methods and tools). It is a specific verb+resource, though it does not explicitly differentiate itself from sibling list_* tools beyond the resource name.

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 supplies clear usage context by saying 'Reference one in create_run by name,' which tells the agent when to call this tool. It stops short of explicit when-not conditions or naming alternative list tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by confirming the operation is read-only and explicitly noting that upload/delete are not available as tools and must go through the REST API — a non-obvious routing fact an agent would otherwise have to guess.

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 waste: resource and returned fields first, then the use case, then the read-only/mutation boundary. 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 compensates by enumerating the returned fields, and it clarifies scope and the mutation boundary. Minor gap: nothing is said about result volume, ordering, or whether the list is paginated, which matters for an org-wide listing.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies no filtering or scoping arguments are needed, listing everything in the organization, which is consistent with the empty object 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 files saved in the organization') and enumerates the returned attributes (id, name, size, content type, creation time). None of the sibling tools touch files, so there is no ambiguity to resolve, and the scope (organization-wide) is explicit.

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

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

Explains the downstream use case ('Reference a file by id in a run's or workflow's files'), which tells the agent why and when to call it. It also names the alternative path for mutation ('upload and delete files through the REST API'), effectively excluding this tool from write scenarios, though it does not call out a specific sibling tool for comparison.

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 read-only/idempotent, and the description adds real behavioral context on top: result shape, inclusion of total count and default model, truncation at default 25 / max 100, and the truncation hint. That is exactly the kind of operational detail annotations cannot carry.

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

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

Two dense sentences, front-loaded with the purpose and the return shape, then actionable routing. The long parenthetical field list is efficient but makes the first sentence heavy; nothing is wasted, though it is close to overpacked.

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

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

No output schema exists, and the description compensates by describing the returned fields, the count, and the default model, plus truncation behavior. An agent can call this correctly and interpret the response without further context.

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; the description still adds value by explaining the limit/truncation interaction, giving concrete query examples ("claude", "gpt"), and clarifying that model returns full details for one item. It does not mention zero_data_retention, the one filter whose effect is least obvious from its name alone.

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

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

"Find models" is a thin opener but the following sentence nails the resource and scope: a compact model catalog with id, name, context_length, pricing and zero_data_retention, plus total count and default model. No sibling tool lists models, so differentiation is clear by default, though the verb could be tighter ("list/search models").

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 when-to-use guidance: filter with query when narrow, read the hint when truncated, pass model (or id) for a single model's full details, and feed the returned id into create_run. It also names the alternative path (detail vs list) and the reason (hundreds of models).

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

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

Annotations already declare this is a safe, read-only, idempotent operation. The description adds useful behavioral context beyond those hints: results are newest first, pagination uses a cursor, and the cost_final/cost_micros fields have provisional billing semantics.

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

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

Two sentences, front-loaded with the core listing behavior. The second sentence carries a relevant return-value caveat without unnecessary repetition or filler.

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

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

With no output schema, the description still covers the key return caveat around provisional cost and explains pagination direction. It leaves status-filter behavior to the schema, which is reasonable, though a brief note on filtering would make it fully 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 67%: limit and cursor are documented in the schema, while status has an enum but no description. The tool description does not add parameter-level meaning beyond the schema, 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 names a specific verb and resource: 'List the organization's runs.' It also states ordering ('newest first') and pagination ('cursor for the next page'), which clearly distinguishes it from single-run siblings like get_run and wait_for_run.

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 'List the organization's runs' and the pagination note, but the description does not explicitly say when to use this instead of get_run or wait_for_run, nor does it state any exclusions or 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 readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds useful return-field context ('next start', 'last run', 'last error'), but it does not mention pagination, result ordering, or permission constraints for a list operation.

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

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

The description is front-loaded with the core action and resource, followed by compact context about schedule behavior and return contents. Both sentences are efficient and contain 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 simple list tool with one optional filter, no output schema, and annotations covering safety, the description is nearly complete. It compensates for the missing output schema by naming key returned fields, though it omits listing behavior such as pagination and ordering.

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

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

Schema description coverage is 100%, and the single optional 'workflow' parameter is already documented in the schema. The description does not add syntax or filtering semantics 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 clear verb and resource ('List the organization's schedules') and explains what a schedule is, including that it starts a saved workflow on a cron timetable. It also states the returned fields, which helps distinguish it from get_schedule, but it does not explicitly name siblings or alternatives.

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 that this tool is for listing schedules, but it gives no explicit guidance on when to use it versus get_schedule, list_workflows, list_runs, or preview_schedule. There are no conditions, exclusions, or prerequisite notes.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context: exactly which fields each entry carries and, importantly, that the input_schema reflects what create_run expects — information not present in annotations or the (empty) input 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 sentences, front-loaded with the core action and scope, with no filler. The second sentence is dense but the parenthetical definitions of input_schema/output_schema earn their space by tying the output to create_run's contract.

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, enumerating the entry fields and the optionality of description/schemas. Minor gaps remain (ordering, whether all workflows are always returned, empty-list behavior), but for a zero-parameter read-only list tool this is sufficient to call 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?

The tool takes zero parameters, which sets a baseline of 4. The description goes slightly further by documenting the fields of each returned entry (name, description, input_schema, output_schema) and what those schemas mean in practice, though with no parameters there is nothing else to disambiguate.

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 organization's saved workflows") and immediately clarifies the domain term with a parenthetical ("reusable run definitions"). It also distinguishes the tool's output from an execution tool by pointing to create_run, so an agent can tell it apart from get_workflow and create_run without opening a schema.

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

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

Gives a clear usage context: use this to discover workflows and their schemas "so you can call a workflow without reading its prompt," then run one with create_run by name. It stops short of naming when to prefer get_workflow for a single workflow or when listing is unnecessary, so it is clear context without explicit exclusions.

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

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

Annotations already declare readOnly and idempotent, so the safety profile is covered. The description adds genuinely new context: the result is exactly five occurrences, returned in UTC regardless of the input timezone, and nothing is persisted — a non-obvious normalization worth stating.

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

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

A single sentence that front-loads the core purpose and ends with the key non-persistence constraint. No filler, no repetition of the 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?

There is no output schema, and the description compensates by specifying the return value (five upcoming start times, in UTC). Only error behavior for an invalid cron expression is unaddressed, a minor gap for a read-only preview tool.

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

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

Schema coverage is 100%, with both cron syntax forms and IANA timezone naming fully documented in the schema. The description only reiterates that both inputs exist and that output is UTC; it adds no syntax or format 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?

The description gives a specific verb ('Check') and resource ('cron expression and time zone') plus a concrete output ('next five start times'). The phrase 'without saving anything' implicitly separates it from create_schedule and run_schedule, though those siblings are never named.

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 is implied as a dry-run/validation step before save_schedule or create_schedule, but the description never states when to prefer this over those tools or what to do when validation fails. 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?

Goes well beyond the annotations by disclosing that every invocation enqueues a separate run and incurs billing 'like any run,' reinforcing the non-idempotent hint with concrete consequence. It also explains that the run inherits the schedule's input and cost cap and returns a queued run to be followed with wait_for_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 tight sentences; the action and its out-of-timetable scope come first, followed by return value, follow-up tool, and cost/duplication warning. 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?

With no output schema, the description still covers the return value (a queued run), the natural next step (wait_for_run), and the cost side effect. 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?

Schema coverage is 100% and the single id parameter is fully documented, so the baseline is 3. The description adds real meaning by clarifying that no inputs are passed here — the run reuses the schedule's stored input and cost cap, which the schema alone does not convey.

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 — 'Start the schedule's workflow now, outside its timetable' — which tells an agent this is an immediate trigger rather than a scheduled or previewed action. It does not explicitly name the nearby alternatives (preview_schedule, create_run), so differentiation from siblings is left partly 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?

Gives clear context for use ('outside its timetable') and a follow-up instruction to call wait_for_run, plus a warning that 'each call starts another run.' It stops short of stating when NOT to use it (e.g., to preview without executing), so the alternative-selection guidance is implicit 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?

Beyond what the annotations declare (idempotent, non-destructive), it explains the replace semantics and confirms idempotency ("saving the same definition again changes nothing more"), that connections must pre-exist in the organization and be referenced by name not URL or credential, and how input_schema/output_schema are enforced at run time including failure modes. This is exactly the kind of context the annotations cannot carry.

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?

Roughly four sentences, all of which earn their place, and the create-or-replace behavior is stated first. Some sentences are long and pack multiple rules (validation behavior, connection referencing), which costs a bit of scanability but no content is filler.

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

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

For a 12-parameter, nested, non-read-only tool with no output schema, the description covers the risky and non-obvious behaviors: wholesale replacement, prerequisite connections, schema contracts and run-failure semantics. It leaves the remaining settings (web, files, shell, model, timeout, retention) entirely to the schema, which is acceptable given 100% coverage but leaves a small 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 the parameter baseline is 3; the description adds real meaning on top by explaining the purpose of input_schema (checked before a run starts, refusal reports path and reason) and output_schema (agent replies JSON only, mismatch fails the run), plus the agent-discoverability rationale for name/description. The remaining 10 parameters are not discussed, so it stops short of full compensation.

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?

"Create a workflow, or replace the one with this name" gives a specific verb (create/replace), resource (workflow) and an explicit upsert-by-name scope. It also distinguishes the tool from its siblings by naming get_workflow as the read path and create_run/create_schedule as the consumers of the saved definition.

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 key sequencing rule outright: "Read the current definition with get_workflow first when you change part of it, because saving replaces the whole definition." That is a concrete when-to-use/when-to-call-something-else instruction, and it further routes prerequisites to list_connections and list_files via the schema-backed field descriptions.

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 real context beyond the annotations: an auth requirement (administrator key), partial-update semantics, the side effect that resuming clears the failures that paused the schedule, and the timing rule that a new timetable counts from now. These are exactly the behavioral facts the idempotent/destructive hints 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?

Four short sentences, front-loaded with the core action and partial-update rule, then prerequisites, then the pause/resume recipe. Every sentence carries information an agent needs; nothing is redundant 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 9-parameter mutation with no output schema, the description covers action, auth, partial-update behavior, pause/resume effects and timing. It omits what the response looks like and whether a cron change affects an already-scheduled next run, which are minor gaps given full schema coverage.

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 meaning the schema lacks: that omitted fields are left untouched, and that flipping enabled to true has the side effect of clearing failure state. It adds nothing for cron/input/workflow beyond the schema, which already documents them.

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 ('Change a schedule') and immediately scopes it as a partial update ('only the fields you give change'), which distinguishes it from create_schedule, delete_schedule and get_schedule. It also covers the pause/resume variant named in the title, so an agent can route to it without opening the schema.

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

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

Gives clear conditions: it needs an administrator key, and enabled=false pauses while enabled=true resumes. It stops short of naming alternatives (e.g. create_schedule to make a new one, run_schedule to trigger one now), so the when-not 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?

Goes well beyond the readOnly/idempotent annotations: it discloses the continued wait for billing settlement (seconds to ~20s), the hard 60-second cap, the retry pattern, and the crucial caveat that cost_micros is provisional when cost_final is false. That is exactly the behavioral context an agent needs before quoting a cost.

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 the core behavior (what it waits for, then returns) before the billing and cost caveats. Slightly repetitive at the end — the provisional-cost warning and 'quote only when cost_final is true' restate the same point — but every other sentence carries information.

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

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

With no output schema, the description carries the return-value burden and does so: it names the returned statuses and the cost_final/cost_micros/billing_pending fields and their interpretation. Nothing an agent needs to call it or trust its result 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 id and timeout_seconds (1–60, default 30) are already fully documented in the schema. The description reinforces the 60-second cap and what happens when the timeout expires, but adds no format or syntax detail beyond the schema. 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 (wait for a run) and enumerates the terminal states it waits for. It is clearly distinguishable from get_run (non-blocking read) and cancel_run (mutation), since the blocking-with-timeout behavior is spelled out.

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

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

Explains the calling pattern: wait up to 60s, and if the run is still going, call it again. It also routes the agent to get_run for provisional-cost rechecks. It doesn't explicitly say when to prefer get_run over wait_for_run up front, so it stops short of full 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.