Trigger.dev MCP by usefulapi

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

The annotations already carry a behavioral signal (destructiveHint=true, title), so the bar is lower. The description usefully adds that activation restores firing behavior, but says nothing about side effects, reversibility, permissions, or the conflicting nuance of a 'destructive' hint on a resume 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?

Two short sentences, effect stated first, API endpoint appended as secondary reference. Nothing is redundant and the key information 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 single-parameter, annotation-backed tool with no output schema, the description covers purpose and effect adequately. Minor gaps remain: no error/edge-case behavior (already active, nonexistent schedule) and no return indication.

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 exactly one parameter and schema description coverage is 100%, so the schema already documents schedule_id fully. The description adds no format, ID-source, or lookup guidance beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (activate/resume) and resource (a paused schedule) plus the observable effect ('so it fires again'). It implicitly contrasts with the sibling trigger_deactivate_schedule through the 'paused' precondition, but never names that alternative, 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?

'Resume a paused schedule' implies the usage context (the schedule must already be paused), but there is no explicit when-to-use/when-not guidance, no mention of the deactivate sibling, and no statement about what happens if the schedule is already active.

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' while the annotations declare destructiveHint=true. That is a direct conflict on the single most important behavioral question for a mutation tool, leaving the agent with contradictory signals about risk.

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 purpose, then a trait claim, then the endpoint reference; nothing is padded. The trait sentence is wrong rather than wasteful, which is scored under behavioral transparency.

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

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

For a mutation tool with no output schema and no readOnly/other safety annotations beyond destructiveHint, the description leaves return behavior, permission requirements, and tag constraints unaddressed, and its 'safe' claim actively misleads about destructiveness.

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

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

Schema description coverage is 100%, with both run_id and tags documented in the schema itself, so the baseline is 3. The description adds no extra semantics for tag format, size limits, or duplicate handling.

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: 'Attach tags to a run', plus the downstream reason (filtering later) and the underlying API route. No sibling tool competes for tagging, so it is effectively distinguishable, though it never names an alternative.

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?

'so you can filter for it later' implies when the tool is useful, but there is no explicit when-to-use/when-not guidance, no mention of limits (e.g. tag count caps or duplicate handling), and no routing to related run 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 destructiveHint=true, and the description's 'Cancel an in-flight run' is consistent with that. It adds the endpoint version caveat ('API v2, not v1') and the HTTP route, which is useful context, but says nothing about reversibility, permissions, or the run's post-cancel state.

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 purpose front-loaded and no wasted prose. The middle clause about API versions is slightly awkwardly worded but does not bloat the definition.

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

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

For a single-parameter tool with no output schema and annotations covering the destructive profile, the description is nearly sufficient. Only post-cancellation behavior is unstated, which is a minor gap given the tool's simplicity.

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

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

Schema coverage is 100% for the single run_id parameter, and the description adds no syntax or format detail beyond it. This is the expected baseline when the schema fully documents the parameter.

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') and resource ('in-flight run'), which immediately distinguishes it from siblings like trigger_replay_run or trigger_reschedule_run without needing their schemas. It does not explicitly name an alternative sibling, but the action is unambiguous.

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

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

The description gives no when-to-use or when-not-to-use guidance, no prerequisites, and does not contrast itself with siblings such as trigger_replay_run. The API-version note is a technical caveat, not usage guidance.

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

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

The destructiveHint=true annotation already carries the main safety signal, and the description usefully adds the operational effect (the schedule stops firing) plus the underlying endpoint. However, it does not disclose whether the pause is reversible, whether in-flight runs are cancelled, or what permissions are required. The word 'Pause' slightly understates the destructive flag but does not outright contradict it.

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, with the usage heuristic second and the API endpoint last. Every sentence carries distinct information with no padding 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 one-parameter tool with a full schema description, no output schema, and a destructiveHint annotation, the description covers purpose, effect, and a usage trigger. The only meaningful gaps are post-deactivation state semantics (reversibility, in-flight runs), which are minor for this tool's simplicity.

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 schedule to pause.'), so the schema already does the heavy lifting. The description adds no format, ID-source, or naming detail beyond what the schema provides — baseline 3 is correct here.

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

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

States a specific verb and resource with its effect: 'Pause a schedule so it stops firing.' An agent can immediately distinguish this from trigger_activate_schedule (the inverse) and from the read-only trigger_get_schedule/trigger_list_schedules siblings without opening any schema.

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

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

Provides a clear usage context: 'The usual first move when a scheduled task is misbehaving.' That tells the agent when this tool is appropriate, but it names no explicit alternative (e.g., trigger_activate_schedule for the reverse, or whether to cancel in-flight runs instead) and gives no when-not-to-use guidance.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds the scope ('every run in a batch') and the underlying endpoint, but says nothing about pagination, response shape, or how incomplete/failed runs are represented. Given annotation coverage, a 3 is fair.

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 scope. The endpoint/API line is mildly redundant but compact and confirms the exact operation mapping.

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 tool with no output schema and annotations covering safety, this is nearly sufficient. Ideally it would hint at the return structure or whether results are available only after the batch completes, but the core need is met.

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 batch_id parameter is fully documented there including the 'batch_...' format. The description 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?

States a specific verb (fetch) and resource (the outcome of every run in a batch), which is unambiguous and clearly distinct from the run/schedule/queue siblings, none of which operate on batches.

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 guidance on when to reach for this versus trigger_get_run or trigger_list_runs, and no prerequisites (e.g. that a batch id must already exist). Usage is only implicitly derivable from the name and resource.

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 covers the safety profile, so the bar is lower. The description adds that the lookup is scoped to the invoking key's environment and that only the currently-serving deployment is returned, which is genuine behavioral context. It does not mention auth/scope failure modes or caching, so it stays mid-range.

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 and scope front-loaded; the trailing API path is arguably redundant with the title but is cheap and useful for verification. 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 compensates by naming the fields returned (version, git ref, status), which is exactly what an agent needs to decide whether to call it. Remaining gaps (error behavior when no deployment exists) are minor for a zero-param read.

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 signals that no identifier is needed because the environment is derived from the API key, which is the one meaningful semantic an agent might otherwise hunt for.

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 current deployment), scopes it to the key's environment, and enumerates the returned fields (version, git ref, status). No sibling tool retrieves deployments, so the differentiation from the list is implicit but unambiguous.

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

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

Usage is implied rather than stated: an agent can infer this is the tool for checking what is live in the current environment. There is no explicit when-to-use/when-not guidance and no named alternative (there is no sibling that reads deployments, so none is needed). Adequate but unelaborated.

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 useful content by enumerating exactly which queue metrics come back (concurrency limit, running count, queued count). It says nothing about auth, rate limits, or what happens for unknown queues, 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 tight sentences with zero filler; what the tool returns is front-loaded before the endpoint 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?

With no output schema, the description compensates by naming the returned fields, and the read-only nature is covered by annotations. For a single-resource GET nothing critical is missing, though error behavior for a bad queue name is 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?

Only one parameter and schema coverage is 100%, so the schema fully documents that 'queue' accepts a name or id. The description adds no syntax or format detail beyond the structured field, 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?

Specific verb (Fetch) plus resource (a single queue) plus the exact data returned (concurrency limit, running count, queued count). The singular 'a single queue' implicitly distinguishes it from the sibling 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?

Usage is only implied: fetch one queue when you need its limits/counts, versus trigger_list_queues for the collection. No explicit when-to-use, prerequisites, or named alternative 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description usefully discloses what the call returns (status, output, error, attempts), but says nothing about error semantics (e.g. what happens for a nonexistent run) or whether results are final versus in-progress. With annotations carrying the read-only signal, a 3 is appropriate.

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 outcome and field list, with the REST endpoint appended. No wasted prose.

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

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

With no output schema, the description does the right thing by naming the returned fields, and the readOnlyHint covers safety. Given a one-parameter read tool, this is nearly complete, missing only status/value semantics for edge cases.

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

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

Schema description coverage is 100% and the single run_id parameter is documented in the schema; the description only echoes the id via the REST path template. Baseline 3 for a fully documented parameter set.

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

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

Clear specific verb (fetch) and resource (a single run), plus an enumeration of the payload fields (status, output, error, attempts) that hints at how it differs from get_run_metadata or get_run_trace. It never names 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?

There is no when-to-use guidance and no mention of alternatives such as trigger_get_run_metadata, trigger_get_run_span, or trigger_list_run_events, which an agent could easily confuse with this result-fetching tool. Usage is only inferred from the noun 'run's outcome'.

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 genuine non-obvious context: the data is mutable and written by the run itself, and it enumerates the content categories (progress, checkpoints, custom state), which tells the agent this is live state rather than a static record.

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 payload description front-loaded before the API reference. The endpoint citation is slightly redundant but does aid traceability; no padding otherwise.

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 one required read-only param, no output schema, and existing annotations, the description is nearly sufficient. Naming the returned content categories compensates for the absent output schema, though it does not specify the metadata's shape or when it may be empty.

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) and schema description coverage is 100%, so the schema fully documents it. The description adds no format, sourcing or validation detail for run_id beyond the endpoint path. 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 (Fetch) and resource (a run's metadata), and disambiguates the resource by listing what it contains: progress, checkpoints, custom state. This clearly separates it from sibling reads like trigger_get_run, trigger_get_run_span and trigger_get_run_trace.

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

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

Usage is implied — call it when you need the run's self-reported mutable state — but there is no explicit when/when-not guidance and no alternative named. It does not tell the agent how it relates to trigger_get_run for general run details.

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 establishes this is a safe read, so the description adds the useful fact that the response includes the span's own logs and attributes. It does not disclose error behavior (missing run/span), pagination, or trace-size limits, but the annotation carries the main safety burden.

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 verb and resource front-loaded and no filler. The endpoint line is mildly redundant with the name but compact and useful for API-oriented agents, so it earns its place.

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

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

With no output schema, the description carries the return-value burden and only partially discharges it ('logs and attributes' hints at shape without structure). For a simple two-param read tool backed by a readOnly annotation this is adequate but leaves the response format under-specified.

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 run_id and span_id are already documented in the schema; baseline 3 applies. The endpoint template shows them as path parameters, but the description adds no format or sourcing 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?

Names a specific verb+resource ('Fetch a single span from a run's trace') and adds scope detail (its own logs and attributes). It distinguishes span-level retrieval from the broader run and trace siblings implicitly, but never names them, so an agent must infer the difference from trigger_get_run_trace/trigger_get_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 the scoping phrase 'a single span from a run's trace' – you reach for this when you need one span rather than the whole trace. However, no when-to-use condition, prerequisites, or alternative (get_run_trace) is stated explicitly.

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

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

readOnlyHint=true already establishes this as a safe, non-mutating read, so the bar is lower. The description still adds real context beyond the annotation by characterizing the payload — full trace, all spans, timings, nesting — plus the underlying endpoint (GET /api/v1/runs/{runId}/trace). It does not mention payload size or pagination/truncation behavior for large traces, which is the remaining gap.

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

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

Three tight clauses: what it returns, when to reach for it, and the backing endpoint. The return scope is front-loaded and nothing is padded or repeated.

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 reasonably well by naming spans, timings and nesting level. Given annotations cover the safety profile and there is only one simple parameter, the definition is nearly complete; only payload-size/pagination caveats are 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, and schema description coverage is 100%, so the schema fully documents run_id. The description adds no format hints (e.g. where to obtain a run id) beyond what the schema provides; 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 (fetch), resource (a run's execution trace) and scope ('every span, with timings and nesting'), which clearly distinguishes it from sibling trigger_get_run_span and trigger_get_run. An agent can tell what it gets back without opening any schema.

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

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

The framing "where did this run spend its time, and where did it break?" gives an explicit diagnostic use case, which is strong practical guidance. It stops short of naming alternatives (e.g. get_run_span for a single span) or stating exclusions, so it is clear context rather than full when/when-not routing.

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

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

Annotations declare readOnlyHint=true, so the safety profile is already covered. The description still adds value by disclosing the payload contents (cron expression, timezone, active state), which matters because there is no output schema, and it maps the call to the underlying GET endpoint. It does not cover error behavior for a missing id, so not 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 short sentences, front-loaded with the action and returned data before the endpoint reference. Nothing is padded, though the endpoint sentence is largely restatement for agents that don't map to REST paths.

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

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

For a one-parameter read tool with readOnlyHint coverage and no output schema, the description supplies the essential missing piece — what the response contains — plus the API mapping. Only error/not-found behavior is absent, which is a minor gap.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema with its 'sched_...' format. The description only repeats the id via the endpoint path template, adding no new syntax or constraint information, 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 (Fetch) and resource (a single schedule) and enumerates the returned fields (cron expression, timezone, active state), so an agent knows exactly what it gets back. The word 'single' implicitly separates it from trigger_list_schedules, but no sibling is named explicitly, keeping it 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?

The description implies the use case by contrasting 'a single schedule' against the sibling list tool, but never states when to prefer this over trigger_list_schedules or that it requires a known schedule_id. Usage is inferable rather than spelled out.

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

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

readOnlyHint=true already establishes the safety profile, so the description needed to add context such as pagination behavior, retention window, or auth requirements. Beyond noting that results include progress, it adds nothing behavioral, and the raw endpoint reference conveys no additional agent-relevant information.

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 purpose front-loaded and no padding. The trailing "Trigger.dev: GET /api/v1/bulk-actions" is largely redundant for an agent that already has the tool name and HTTP semantics.

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 list tool the description is roughly adequate, but with no output schema it should at least hint at the shape of returned items or how pagination/next-page behaves given the pageSize parameter. Those gaps leave the agent guessing about result structure.

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 (pageSize) exists and schema description coverage is 100%, so the schema fully documents it. The description adds no format, default, or interaction detail for pagination, 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?

The description states a specific verb and resource ("List bulk replay and cancel operations") and adds scope detail ("their progress"). It is clear what the tool returns, though it never contrasts itself with the single-run sibling trigger_replay_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 only implied: an agent can infer this is for inspecting existing bulk operations, but there is no explicit when-to-use, when-not-to-use, or named alternative. The mention of "bulk" versus the sibling trigger_replay_run is an indirect signal at best.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this while adding genuinely new behavioral detail: values may be redacted depending on the key's permissions. That redaction behavior is exactly the kind of context annotations don't 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?

Two tight sentences plus an endpoint reference, with the core purpose front-loaded and the read-only/redaction caveats following. Every clause earns its place with no 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 two-parameter read tool with no output schema, the description covers the essential behavior, including the permission-driven redaction of returned values. Only the return shape (list format, pagination) is left unaddressed, which is minor here.

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 (project_ref, environment enum) are already documented in the schema. The description adds nothing parameter-specific beyond what the structured fields provide, making the baseline 3 correct.

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 ('environment variables configured for a project environment') with clear scope. No sibling tool touches env vars, and the description makes the domain unmistakable, so the 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?

Clarifies that this server exposes no env-var writes and that values may be redacted, giving the agent a clear read-only context. There is no competing alternative to name, but it stops just short of explicit when-to-use framing.

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 usefully adds what the listing surfaces (concurrency limits and current depth), but says nothing about pagination behavior or result ordering despite exposing a pageSize parameter.

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 gives purpose, payload, and usage cue; the endpoint reference is short. Nothing is wasted or buried.

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

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

For a read-only list tool with no output schema and annotations covering safety, the description says enough to call it correctly. The only gap is paging/return ordering behavior, which is minor here.

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 pageSize parameter is fully documented there with a 1-100 range. The description adds no extra meaning about paging, 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 task queues') and goes further by naming the returned fields (concurrency limits, current depth). The plural 'queues' plus these fields naturally separates it from the singular sibling trigger_get_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?

'where you look when work is backing up' gives a clear situational trigger for reaching for this tool rather than a single-queue lookup. It does not explicitly name trigger_get_queue as the alternative for drilling into one queue, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful behavioral detail by naming the event types returned (queued, dequeued, started, retried, completed) and citing the backing endpoint. It omits ordering/pagination behavior, so it is not exhaustive.

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 carrying the verb, resource, scope, and event enumeration, plus a compact endpoint reference. Every clause earns its place with no 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-parameter read tool with readOnlyHint annotations and no output schema, the description supplies the return-value content (event types) that would otherwise be missing. It lacks ordering or pagination notes, which is a minor residual 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 parameter and schema description coverage is 100%, so the schema already documents run_id fully. The URL template in the description reinforces that run_id is a path parameter but adds little semantic meaning 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 (lifecycle events of one run) and even enumerates the event kinds returned. This is far more precise than a bare 'get events' phrasing, though it does not explicitly differentiate itself from close siblings like trigger_get_run or trigger_get_run_trace.

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 this is for inspecting a run's lifecycle, but there is no statement of when to prefer this over trigger_get_run, trigger_get_run_trace, or trigger_get_run_span, nor 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?

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the description's 'main read' framing is largely redundant. It adds the backing HTTP endpoint (GET /api/v1/runs) but says nothing about pagination behavior, result volume, or the 100-item page cap, which would have been genuinely useful 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?

Two tight sentences with the verb and filter set front-loaded, then the usage framing. The trailing 'Trigger.dev: GET /api/v1/runs' is mildly extraneous for an agent choosing a tool, but costs little.

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

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

For a read-only list tool with 100% schema coverage and a readOnlyHint annotation, the description covers purpose and filter scope adequately. It does not address pagination or default result behavior, but with no output schema the pageSize/after params in the schema carry most of that burden.

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

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

Schema description coverage is 100%, so all 14 filter parameters are already documented in the schema. The description only groups them ('status, task, tag, queue, schedule or a time window') without adding format or precedence detail beyond what the schema provides, which is the baseline for full coverage.

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 ('List task runs') and enumerates the filtering dimensions, so an agent immediately knows this is the bulk read over runs. It stops short of naming the contrasting siblings (trigger_get_run for a single run, trigger_list_run_events for event-level detail), so it is clear but not fully differentiated.

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 line 'This is the main read for "what ran, and what failed?"' gives clear situational context for choosing this tool. There are no explicit exclusions or named alternatives (e.g. when to prefer trigger_get_run or trigger_list_run_events instead), so it never reaches 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 declare readOnlyHint=true, so safety is covered by structured data. The description adds that results include next run times, which is useful output context, but says nothing about pagination behavior, auth requirements, or result ordering beyond what the schema provides.

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. The purpose and return-value hint are front-loaded, and the API endpoint reference is compact trailing context. No waste.

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 list tool with a fully documented 2-parameter schema and readOnlyHint annotation, the description covers what and what-comes-back. Only pagination semantics (defaults, whether next-page info is returned with no output schema) 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% with both page and pageSize fully documented (including ranges). The description adds no parameter detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (List) and resource (cron schedules for tasks), and adds the meaningful detail that next run times are included. An agent can distinguish this from trigger_get_schedule (singular) and trigger_list_queues/runs 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 description implies this is the discovery/browse operation for schedules, but never states when to use it versus trigger_get_schedule or the activate/deactivate siblings. Usage context is implied by the verb but not made 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?

readOnlyHint=true already covers the safety profile, so the description only needs to add context. It does add 'outstanding' (i.e. only unresolved tokens, not the full history) and names the underlying endpoint, but says nothing about auth scope, rate limits, or ordering.

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

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

Two compact clauses with the resource and its meaning front-loaded; no filler sentences and the endpoint reference is tacked on at the end where it does no harm.

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 list tool with fully documented pagination params, the description is minimally sufficient, but with no output schema it never hints at what a waitpoint token record contains (id, url, status), leaving the return side entirely to inference.

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 (after cursor, pageSize 1-100) are fully documented in the schema. 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 ('List ... waitpoint tokens') and disambiguates the domain concept by explaining these are 'runs paused waiting for an external signal'. No sibling lists waitpoints, so there is no real ambiguity, though it never explicitly contrasts itself with trigger_list_runs or other list tools.

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

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

Usage is implied by 'outstanding waitpoint tokens' — the agent can infer this is for inspecting pending external-signal pauses — but there is no explicit when-to-use, when-not-to-use, or alternative tool guidance.

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

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

Annotations only supply destructiveHint=true; the description usefully adds that pausing stops dequeuing of runs, which is behavioral detail beyond the annotation. It does not say what happens to already-dequeued or in-flight runs, nor confirm the action is reversible (though 'or resume it' implies so). Adequate but incomplete.

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 action and mechanism front-loaded, plus the endpoint. Nothing is wasted.

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

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

For a two-parameter tool with full schema coverage and no output schema, the description covers purpose, triggering scenario, and one behavioral effect. It stops short of noting reversibility guarantees or the fate of 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 both parameters fully described ('queue' name or id, 'paused' true/false), so the schema does the heavy lifting. The description adds no extra syntax 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?

States a specific verb and resource ('pause a queue so its runs stop being dequeued, or resume it') and clarifies the mechanism, which distinguishes it from read-only 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 clear when-to-use scenario ('the containment move when a task is failing in a loop') but names no alternative tool, so an agent must infer that trigger_cancel_run and trigger_replay_run are not substitutes.

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 destructiveHint annotation already flags this as a write/destructive operation, but the description earns credit by spelling out what that means: it EXECUTES the production task again with the same side effects as the original run. It stops short of describing return behavior, idempotency, or auth requirements.

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 immediately followed by the critical side-effect warning the agent most needs. Every sentence earns its place.

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

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

For a one-parameter re-trigger tool with no output schema, the description covers the essential action and its destructive consequence well. It could be slightly more complete by noting what is returned (e.g., a new run id) or that the replay is async, 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?

Schema description coverage is 100% for the single required run_id parameter, so the schema already carries the parameter semantics. The description's {runId} path reference adds nothing beyond what the schema states, 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 gives a specific verb+resource: 'Re-run one specific past run with the same payload,' which an agent can act on directly. It does not, however, distinguish this from the sibling trigger_reschedule_run, which an agent could easily confuse it with.

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 strong caution that this re-executes the production task with the same side effects, signaling it should only be used when a deliberate re-execution is wanted. No explicit alternatives (e.g., trigger_get_run to inspect, trigger_cancel_run to stop) are named, so the when-not guidance is left to inference.

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

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

Annotations already declare destructiveHint=true, so the mutation risk is covered. The description usefully adds the not-started precondition, but it does not disclose what happens to the previous delay value, whether the change is reversible, or any auth/permission requirements.

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 plus an endpoint reference, with the core action front-loaded and the precondition immediately after. The endpoint citation is mildly redundant but does not bloat the definition.

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 mutation with no output schema, the description covers the action and its precondition but says nothing about the response or error conditions. Adequate but leaves the agent without confirmation of what a successful reschedule yields.

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 documented with format examples ('1h' or ISO-8601). The description adds only the conceptual framing of 'a delayed run' and nothing about accepted delay formats 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 ('change when a delayed run will execute') that clearly distinguishes it from sibling mutations like cancel_run or replay_run, and names the underlying endpoint. The scope is narrower and more precise than a generic 'update 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?

Provides an explicit precondition — 'only applies to runs that have not started' — which tells the agent when the tool is valid versus when it will fail. It does not name a fallback tool for runs that have already started, so it falls short of full routing guidance.

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