trigger-dev

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

Annotations already flag destructiveHint=true, and the description is consistent with that by explaining the schedule will fire again (side effects resume). It adds the HTTP method/endpoint, which is mildly useful, but says nothing about permissions, what 'paused' state means, or side effects on in-flight runs. 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 short sentences with the core action front-loaded and no filler. The trailing API endpoint reference is marginally useful metadata but slightly redundant with the tool name.

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

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

For a one-parameter toggle tool with no output schema, the description covers the essential action and state transition, and annotations carry the destructive safety signal. Missing only permission prerequisites and any note about in-flight 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?

Schema coverage is 100% with a single self-documenting 'schedule_id' parameter, so the baseline of 3 applies. The description adds no format or syntax detail beyond the schema (it even spells the path field 'scheduleId', a minor naming mismatch).

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: resumes a paused schedule so it fires again. The pause/resume framing implicitly contrasts with trigger_deactivate_schedule, but that sibling is never named, so differentiation is inferred rather than 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?

'Resume a paused schedule' implies the precondition (the schedule must be paused), which is useful implied guidance. However, there is no explicit when-to-use, when-not, or naming of the deactivate alternative that would let an agent confidently route between the two.

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 asserts 'Additive and safe', but the annotations declare destructiveHint=true. This is a direct contradiction that would mislead an agent about the mutation risk of calling the tool, and no other behavioral context (permissions, whether existing tags are replaced, return behavior) is supplied.

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, front-loaded fragments: purpose and benefit first, behavior claim second, endpoint last. No filler or repetition; every clause carries information.

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

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

For a trivial two-required-parameter tool with no output schema, the description covers what the call does and what it is for, which is nearly enough. Its completeness is undercut only by the inaccurate safety claim and the absence of any note on whether supplied tags replace or extend existing ones.

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 only two simple parameters, so the schema already explains both run_id and tags. The description adds no syntax, format, or constraint detail (e.g. tag length/character limits, append-vs-replace semantics) beyond what is structured. 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+resource ('Attach tags to a run') plus the downstream benefit ('so you can filter for it later'), and nothing else in the sibling list does tagging, so the agent can place it unambiguously. The concrete endpoint (POST /api/v1/runs/{runId}/tags) reinforces exactly what operation is performed.

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 clause 'so you can filter for it later' implies the use case (organizing runs for later retrieval), which is implicit guidance only. It names no alternatives or exclusions - e.g. nothing about whether this replaces or complements trigger_get_run_metadata or trigger_list_runs filtering.

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, so the agent knows this is a mutating operation. The description adds the meaningful constraint that only in-flight runs are cancellable, but is silent on irreversibility, permissions, or what state the run ends in; the API-version note is endpoint trivia rather than behavioral context.

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

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

The purpose is front-loaded in one tight sentence, but the second sentence about v2 vs v1 and the raw 'Trigger.dev: POST /api/v2/runs/{runId}/cancel' string adds little for an agent choosing a tool and reads as internal documentation spillover.

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 mutation tool with destructiveHint annotated and no output schema, the description supplies the essential purpose and the in-flight scope. It is nearly complete; a sentence on the resulting run state or required permissions would close the remaining 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?

There is a single required parameter with 100% schema description coverage ('The run to cancel.'), so the schema already carries parameter meaning. The description only echoes runId inside the raw path template, adding no semantics 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 ('Cancel an in-flight run') and scopes it to in-flight runs, which no sibling tool does (the closest siblings, replay_run and reschedule_run, do something different). An agent can identify the tool's job without opening the schema.

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

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

The 'in-flight' qualifier implies the tool applies only to currently executing runs, which is a useful usage boundary, but the description never explicitly states when to reach for this versus replay_run or reschedule_run, nor any prerequisite such as run state. Usage is implied rather than specified.

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, and the description usefully clarifies the operation's effect ('stops firing') and implies the schedule is paused rather than deleted. There is a mild tension between 'pause' (suggesting reversibility) and a destructive hint, but nothing is explicitly stated about reversibility, permissions, or how to resume. Adds some behavioral value but not rich context.

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

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

Three short sentences, front-loaded with the effect and the usage cue; the API endpoint is appended as a useful routing detail. Slightly more than strictly necessary but no sentence is wasteful.

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

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

For a one-parameter tool with no output schema and an annotation carrying the safety profile, the description covers the effect and when to use it adequately. It could note reversibility or point to the activate counterpart, but nothing essential for correct invocation is missing.

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

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

There is a single parameter and schema description coverage is 100%, so the schema fully documents schedule_id ('The schedule to pause'). The description adds nothing beyond what the schema already conveys, which is the expected baseline for full-coverage schemas.

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 ('Pause a schedule so it stops firing') that an agent can immediately map to a mutation of one schedule. It does not name the converse sibling trigger_activate_schedule, but the verb 'pause' makes the contrast obvious enough to distinguish it from activation.

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 usual first move when a scheduled task is misbehaving' gives a situational cue for when to reach for this tool, which is more than nothing. However, it names no alternative (e.g. trigger_reschedule_run or trigger_deactivate vs. queue pausing) and no when-not condition, so the agent still has to infer the rest.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds that the response covers every run in the batch (an aggregate, not a single result), which is useful, but says nothing about pagination, partial/failed runs, or whether results are available before the batch finishes.

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

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

Two compact sentences, the primary purpose front-loaded and the API reference trailing. No filler; the endpoint mention is arguably redundant but harmless.

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-param read tool with annotations covering the safety profile, this is close to adequate, but with no output schema the description should give at least a hint of the return shape (per-run outcome, error handling), and it doesn't.

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 with 100% schema coverage; the schema already documents the batch_id format (batch_...). The description adds the path mapping GET /api/v1/batches/{batchId}/results but no new constraints beyond what the schema gives.

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

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

States a specific verb ('Fetch') and resource ('the outcome of every run in a batch'), backed by the exact REST endpoint. No sibling tool in the list deals with batches, so the agent can distinguish it from run-level reads like trigger_get_run, though the description never explicitly contrasts itself with those.

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

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

There is no guidance on when to call this versus the many run-level siblings (trigger_get_run, trigger_list_runs, trigger_get_run_metadata). The phrase 'every run in a batch' implies a batch-scoped aggregation, but no prerequisite (batch must be complete), timing, or exclusion is stated.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds that the result covers version, git ref and status and scopes it to the key's environment, but says nothing about auth requirements or error 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?

Two short sentences, scope front-loaded, and the endpoint reference added at the end without padding. Every clause carries information.

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

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

For a zero-parameter read with no output schema, the description usefully enumerates the returned fields (version, git ref, status) and the environment scoping. It is close to complete, though it omits any note on what happens when no deployment exists.

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

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

The tool takes zero parameters, so there is no per-parameter semantics to document; the baseline for a parameterless tool 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 (Fetch) and resource (the deployment currently serving the key's environment), plus the exact API endpoint. No sibling tool covers deployments, so it is unambiguously distinguishable.

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

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

Usage is implied by the scope ("currently serving the key's environment"), so an agent can infer it is a point-in-time read, but there is no explicit when-to-use or when-not-to-use guidance and no named 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?

The annotations already declare readOnlyHint=true, covering the safety profile. The description adds valuable return-value context by naming the three counters returned, which goes beyond the annotations and helps set expectations for the response.

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 tightly written sentences with zero waste. The core action and its result are front-loaded, followed by the API endpoint as a helpful reference.

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 simple single-queue read operation, the absence of an output schema, and annotations that already cover read-only safety, the description is complete enough. It states the operation, the returned data, and the underlying API endpoint.

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 parameter 'queue' is fully documented as 'The queue's name or id.' The description adds no further syntax, format, or constraint details beyond what the schema already provides, 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 states a specific verb ('Fetch') and resource ('a single queue'), and enumerates the returned fields (concurrency limit, running count, queued count). It implicitly distinguishes itself from the sibling 'trigger_list_queues' by specifying 'a single queue'.

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

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

The phrase 'Fetch a single queue's...' gives clear context that the tool is for retrieving one specific queue when its identifier is known. It does not explicitly name the alternative sibling 'trigger_list_queues' or state when not to use this tool, so it falls short of a full 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 declare readOnlyHint=true, so the safety profile is covered. The description adds value by enumerating what the response contains (status, output, error, attempts) even though no output schema exists, but it says nothing about failure modes, missing-run behavior, or size/pagination of results.

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

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

Two short sentences, front-loaded with the payload summary. The API endpoint sentence is mildly redundant but does confirm the resource path and the runId placement; nothing else is wasted.

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

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

For a single-parameter read-only fetch with no output schema, the description covers what an agent needs: the resource, the required identifier, and what comes back. Only the sibling-routing question (which of the several run-related getters to call) is left open.

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 one parameter at 100% schema description coverage, the schema already documents run_id and its run_... format. The description contributes only the API path hint and adds no semantics beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ("Fetch a single run's outcome") and enumerates the returned fields — status, output, error, attempts — which separates it from metadata/span/trace siblings. It stops short of naming those siblings explicitly, so the differentiation is implied 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?

The description implies the usage context (you have a run_id and need that run's result), but gives no when/when-not guidance against the many closely-named siblings such as trigger_get_run_metadata, trigger_get_run_span, trigger_get_run_trace, or trigger_list_runs. An agent must infer the routing itself.

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 safety profile is covered. The description adds genuinely useful context beyond that: the metadata is 'mutable' and is what the run 'has written about itself', telling the agent this is run-emitted state rather than static configuration. It does not cover return shape or pagination, keeping it short of a 5.

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

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

Two compact sentences, front-loaded with the resource and payload description, with the API path placed last as a verification aid. No filler or redundancy.

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

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

For a single-required-param read tool with no output schema, the description adequately conveys what is retrieved (progress, checkpoints, custom state). It could say slightly more about expected return shape, but the annotations and schema cover the rest.

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 parameter with 100% schema description coverage ('The run's id.'), so the schema already carries the semantics. The description adds no format, sourcing, or constraint detail beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb+resource ('Fetch the mutable metadata a run has written about itself') and enumerates the metadata kind (progress, checkpoints, custom state), which distinguishes it from generic run retrieval. However, it never names or contrasts with the adjacent sibling trigger_get_run, so the agent must infer the boundary between run metadata and run details.

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: an agent can infer that this is the tool for reading self-reported run state, but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. trigger_get_run for full run details) to route between the two.

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 profile is covered structurally. The description adds that the span comes with its own logs and attributes, which is useful return-shape context, but says nothing about auth, pagination, or tracing 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?

Two tight sentences with the resource description front-loaded and the REST path appended. No filler, though the endpoint line adds little for an agent that already knows the parameters.

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

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

For a two-parameter read tool with full schema coverage and a readOnlyHint, this is nearly complete; it even hints at the returned payload. The one gap is the missing disambiguation from trigger_get_run_trace.

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 both required parameters are documented in the schema itself, so the description isn't needed to explain them. It adds only the endpoint template showing runId/spanId placement, which is marginal 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 ('Fetch a single span from a run's trace'), which sets it apart from most siblings. It doesn't explicitly distinguish itself from the closest sibling, trigger_get_run_trace (whole trace vs one span), so an agent must infer that boundary.

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 when-to-use guidance, no prerequisites, and no alternatives named. The obvious alternative, trigger_get_run_trace, is never mentioned even though the two overlap heavily in intent.

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 profile is covered without help from the description. The description adds useful behavioral context about the payload ('every span, with timings and nesting') and pins the underlying API call. It says nothing about trace size, truncation, pagination, or auth requirements, so it is a moderate-but-not-rich addition given the annotation coverage.

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 action and scope before the use-case framing. The trailing 'Trigger.dev: GET /api/v1/runs/{runId}/trace.' is largely provenance filler that duplicates the operation already stated, keeping it just short of a perfect score.

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 read tool with readOnlyHint set and no output schema, the description covers purpose, the debugging use case, and the shape of what is returned (spans, timings, nesting). It lacks any note on response volume or handling of very large traces, which is the only real gap for an agent calling it blind.

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 parameter (run_id) with 100% schema description coverage ('The run's id.'). Per the rubric this is the baseline 3: the schema fully documents the parameter and the description adds no format, source, or constraint detail beyond it.

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 ('Fetch the full execution trace of a run') and scopes it precisely with 'every span, with timings and nesting.' This implicitly separates it from the sibling trigger_get_run_span (single span) and trigger_get_run (run summary/status), but neither sibling is named explicitly, so the differentiation is left 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?

The framing 'The tool for "where did this run spend its time, and where did it break?"' gives a clear, concrete use case that an agent can match to a debugging/performance task. It stops short of stating when NOT to use it or naming alternatives (e.g., use trigger_get_run_span for one span), so it doesn't reach the explicit when/when-not bar.

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?

readOnlyHint=true already declares this is a safe read, so the safety profile is covered by annotations. The description adds the returned field set, which is useful given there is no output schema, but says nothing about auth requirements, error behavior, or what happens for an invalid id.

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, front-loaded with the purpose before the API route. 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?

With no output schema, the description usefully names the fields a caller can expect, and the single parameter is fully covered by the schema. ccccMissing only error/not-found behavior, which is a minor gap for a 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% and the single schedule_id parameter is documented in the schema with its sched_ prefix. The description adds no syntax or format detail beyond that, so baseline 3 applies.

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

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

States a specific verb and resource (fetch a single schedule) and enumerates what it returns (cron expression, timezone, active state). This cleanly distinguishes it from the sibling trigger_list_schedules, which returns many.

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

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

Usage is implied by the singular 'a single schedule' versus the list sibling, but there is no explicit when-to-use statement or mention of the alternative. An agent can infer it, but the definition does not spell it out.

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

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

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the description's burden is lower. It adds that results include operation progress, which is real context, but says nothing about pagination behavior, ordering, or how an in-progress vs. finished bulk action is represented.

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

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

Two short sentences, zero filler, with the operation list front-loaded and the endpoint reference trailing. Efficient, though the endpoint citation is low-value for an agent that cannot call HTTP directly.

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 ideally would sketch the returned shape, yet it only mentions "their progress" in passing. For a single-parameter list tool this is minimally adequate, but pagination and result structure remain unexplained.

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 pageSize parameter with its 1-100 bounds, so the schema already carries the parameter semantics fully. The description adds no constraint or default beyond what the schema states, making 3 the correct 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?

States a specific verb and resource ("List bulk replay and cancel operations") and adds the useful detail that progress is included, plus the backing endpoint. It does not explicitly distinguish itself from close siblings like trigger_get_batch_results, so an agent must infer that bulk actions are the async batch-level operations rather than individual run results.

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 when-to-use guidance is given. The description never says to call this to monitor an in-flight bulk replay/cancel, nor does it name trigger_get_batch_results, trigger_replay_run, or trigger_cancel_run as alternatives, leaving the agent to infer selection from the name alone.

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 safety profile is covered; the description adds real value on top: values may be redacted depending on the key's permissions, and the tool maps to GET /api/v1/projects/{projectRef}/envvars/{env}. It does not describe ordering or pagination, but for a small config list that is minor.

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, purpose front-loaded, then the redaction caveat, then the read-only constraint. The trailing endpoint citation is mildly redundant but is compact and aids traceability; nothing else is wasted.

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

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

For a two-parameter read-only list with full schema coverage, existing annotations, and no output schema, the description covers everything an agent needs: what it returns in principle, the redaction caveat, and the absence of write capability.

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 an enum on environment and a documented project_ref format, so the schema carries parameter semantics. The description adds nothing about parameter format or constraints, which is the expected baseline when the schema is this complete.

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 environment variables configured for a project environment'), and the resource is unique among siblings that all concern runs, queues, schedules, and deployments. An agent can pick this tool without opening the schema.

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

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

Usage context is clear (listing env vars for a given project/environment) and it explicitly rules out a class of alternatives by noting no env-var writes exist on this server, which stops an agent hunting for a write sibling. No explicit when-not or named alternative is given, but there is no overlapping sibling to disambiguate.

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 safety profile is covered. The description adds the useful detail that each item carries concurrency limits and current depth, but says nothing about pagination behavior or total-count semantics despite exposing a pageSize parameter. Modest value beyond 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?

Two compact clauses: the action plus payload, then the practical framing. The core purpose is front-loaded and nothing is wasted; the appended endpoint reference is a minor but tolerable addition.

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

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

With no output schema, the description does touch on return content (concurrency limits, current depth), which is the key thing an agent needs. Given readOnly annotations cover safety and the single parameter is fully documented, the definition is nearly complete, lacking only pagination/response-shape detail.

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 pageSize parameter (with min/max documented in-schema), so the description need carry no parameter burden. Baseline 3 is appropriate; the description adds no additional meaning to pageSize.

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 task queues') and goes further by naming what each entry contains (concurrency limits, current depth). It implicitly distinguishes itself from the singular trigger_get_queue sibling by being the collection-level read, but it never explicitly contrasts with it.

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

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

The clause 'where you look when work is backing up' gives a diagnostic usage context, which is helpful but implied rather than an explicit condition. It never names alternatives such as trigger_get_queue for a single queue or trigger_pause_queue for remediation, so the agent must infer when this is the right call.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds value by enumerating the event kinds it returns, but says nothing about ordering, pagination, or result limits 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?

One tight sentence front-loads the purpose and event scope, with a compact API endpoint reference that aids doc cross-referencing. 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 usefully enumerates the returned event types, which is the main thing an agent needs. It stops short of covering ordering or pagination, which for a list endpoint is a minor remaining gap.

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

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

Only one parameter (run_id) with 100% schema description coverage, so the schema fully documents it. The description's phrase 'of one run' reinforces the single-run scoping 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 (List) and resource (a single run's lifecycle events), and enumerates the event types returned (queued, dequeued, started, retried, completed). It clearly separates this from trigger_get_run by scoping to events rather than run details, though it doesn't name the sibling explicitly.

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

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

Usage is only implied: an agent can infer you'd call this to inspect a run's history, but the description gives no explicit when-to-use, when-not-to-use, or alternative (e.g., trigger_get_run_trace for spans, trigger_get_run for current state).

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?

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the bar is lower. The description adds the HTTP endpoint and the notion that this is the primary read surface, but discloses nothing about pagination defaults, rate limits, or result volume — gaps the schema's 'after'/'pageSize' only partially cover.

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, both earning their place: the first front-loads the resource and filter surface, the second gives intent and the API endpoint. No filler, no restatement of the tool name.

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

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

For a 14-parameter, all-optional list tool whose schema is fully described and whose annotations carry the safety profile, the description is close to sufficient. The one real gap is that no output schema exists and the description never characterizes the returned run records or pagination 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?

Schema description coverage is 100%, so every one of the 14 parameters is already documented in the schema; baseline 3 applies. The description's enumeration (status, task, tag, queue, schedule, time window) loosely maps to some of those parameters but adds no syntax, format, or interaction detail beyond the schema.

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

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

States a specific verb and resource ('List task runs') plus the filter dimensions that scope it, and frames intent as 'the main read for what ran, and what failed?'. It is clear what the tool does, but it never names a sibling it is not — e.g. trigger_get_run for a single run or trigger_list_run_events for events — so differentiation is left 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?

'This is the main read for what ran, and what failed?' implies the default listing use case, which is a genuine routing hint. However there is no explicit when/when-not guidance, no mention of the paginated/cursor nature of the call, and no named alternative for fetching a single run or its events.

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 profile is covered. The description adds that results include next run times, which is useful return context, but says nothing about pagination behavior, result limits, or empty states.

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

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

Two short sentences, front-loaded with the purpose. The trailing API endpoint reference (GET /api/v1/schedules) is mildly redundant but compact and useful for API-oriented agents.

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, no-required-param read tool with full schema coverage and a readOnlyHint, the description covers purpose and the shape of what is returned. Pagination defaults are the only notable gap, and there is no output schema to rely on.

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

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

Schema description coverage is 100%, so page and pageSize are fully documented in the schema. The description adds no pagination or filtering semantics beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the cron schedules configured for tasks') and adds the returned scope ('with their next run times'). It is clearly distinguishable from the singular trigger_get_schedule sibling, though it never names that alternative explicitly.

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

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

There is no when-to-use or when-not-to-use guidance, and no mention of the obvious alternative trigger_get_schedule for a single schedule. Usage is only implied by the verb 'List'.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description's remaining burden is light. It clarifies that the listed entities represent paused runs, but says nothing about pagination behavior, result volume, or rate limits beyond what the schema's cursor/pageSize params imply.

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

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

Two compact sentences and the resource is front-loaded. The endpoint reference is slightly redundant for an agent, but the whole description is short 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?

No output schema exists, so the description arguably should sketch the return shape (token fields, pagination envelope), and it does not. For a simple two-optional-param read tool whose params are fully documented, this is adequate but leaves the response format unspecified.

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

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

Schema description coverage is 100% (after and pageSize are both documented with bounds and purpose), so the schema carries full parameter meaning. The description adds nothing about parameters, which is the expected baseline when coverage is complete.

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 outstanding waitpoint tokens') and adds a conceptual gloss ('runs paused waiting for an external signal') plus the underlying API route. An agent immediately knows what this returns. It doesn't explicitly contrast with siblings, but no sibling covers waitpoints, so the gap is minor.

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

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

There is no when-to-use or when-not-to-use guidance and no named alternatives among the trigger_* siblings. Usage is only inferable from the purpose statement itself.

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 supply only destructiveHint=true; the description usefully clarifies the mechanism (dequeue stops) and implies reversibility via 'resume it'. But it omits key behavioral detail for a pause operation, such as what happens to already-running/in-flight runs and whether pause is idempotent.

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 action and effect; the containment-use framing is placed early. The trailing API endpoint line is mildly redundant with the title but still informative.

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 two-parameter toggle tool with no output schema and minimal annotations, the description covers purpose, effect, and a use case adequately. The remaining gap—impact on in-flight runs—is minor but would be worth adding.

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

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

Schema description coverage is 100%, so both parameters are already fully documented, including the true=pause/false=resume mapping. The description adds no syntax or format information beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (pause) on a specific resource (queue) with the concrete effect ('runs stop being dequeued'), and explicitly covers the inverse operation (resume). It is clearly distinguishable from siblings like trigger_get_queue and trigger_list_queues.

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

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

Gives a concrete when-to-use scenario: 'the containment move when a task is failing in a loop.' However, it offers no exclusions or named alternatives (e.g. cancel_run vs pause), so the agent must infer the boundary conditions.

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?

Although destructiveHint=true already flags danger, the description adds real value by spelling out that the production task executes again with the same payload and the same side effects as the first run. It does not discuss permissions, idempotency, or rate limits, but the side-effect warning is the key behavioral fact here.

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 plus an API endpoint reference; the side-effect warning is front-loaded and nothing is padded. The trailing endpoint string is mildly redundant but grounds the call in the underlying API.

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

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

For a single-parameter destructive action with no output schema, the description supplies the essentials: what is rerun, with what payload, and the side-effect consequence. It could go slightly further on what the call returns or whether duplicates accumulate, but nothing critical is missing.

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

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

Only one parameter with 100% schema description coverage, so the schema already documents run_id. The description adds no syntax or format detail beyond 'the run to replay', which is the expected baseline when 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 (re-run/replay) and a precisely scoped resource (one specific past run), so it is immediately distinguishable from sibling reads such as trigger_get_run or trigger_list_runs. The payload-reuse semantics sharpen the purpose further.

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: it replays a past run rather than creating or fetching one, and the description warns it re-executes the production task. However, it names no alternative (e.g. when to reschedule vs. replay) and no conditions for when not to use it.

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

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

Annotations already declare destructiveHint=true, so the safety profile is covered. The description adds the useful precondition about unstarted runs, but does not explain the destructive aspect (overwriting the prior delay), required permissions, or whether the old schedule is recoverable.

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

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

Two short sentences, front-loaded with the action and then the constraint. The trailing API endpoint is mildly redundant but inexpensive. 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 two-required-parameter mutation with no output schema, the description covers the action, the precondition, and the underlying API call. Only the semantics of replacing an existing delay and permission requirements are left unstated.

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

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

Schema description coverage is 100% and both parameters (delay, run_id) are documented with format examples in the schema. The description adds nothing beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource: changing when a delayed run executes. It also confines the operation to runs that have not started, which sharpens the scope. It doesn't name a sibling (e.g., replay_run) to contrast against, so it falls just short of a 5.

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?

"Only applies to runs that have not started" is an explicit when-not condition an agent can check before calling. However, it names no alternative tool for runs that have already started (replay_run or cancel_run would be the natural siblings), so routing guidance is incomplete.

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