self-starter

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the call surfaces version, CLIs, trigger counts and today's runs, which is useful, but says nothing about whether the check starts a stopped service, how expensive it is, or how failures surface.

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

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

A single sentence that front-loads the target ('the Self-Starter background service') and then lists the returned facts. Every clause earns its place and nothing is repeated from the annotations.

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

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

With no input parameters and no output schema, the description carries the job of saying what comes back, and it enumerates four categories of returned data. The only gap is that the shape of those values (e.g. what a 'trigger count' or 'today's agent runs' entry looks like) is unspecified.

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

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

The tool takes no parameters at all, so there is nothing for the description to disambiguate and the baseline of 4 applies. The schema and description are consistent in describing a parameterless inspection call.

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 pairs a concrete verb ('Check') with a specific resource ('Self-Starter background service') and enumerates what is inspected: version, available agent CLIs, trigger counts, and today's agent runs. That clearly separates it from the trigger_* siblings, which all operate on individual triggers rather than overall service state.

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

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

Use is only implied by the content listed — an agent can infer this is the diagnostic/health check to run before working with triggers. There is no explicit when-to-use guidance, no prerequisites, and no statement of what to do instead if the service is down.

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

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

Annotations only declare this as non-read-only and non-destructive; the description adds substantial context beyond that — the probe runs on a schedule, each fire hands the task back to the agent, and the trigger persists on its own afterwards. That autonomy/persistence disclosure is exactly the behavior an agent needs before calling. It does not say how to undo it or what the immediate response contains, which keeps it below 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 with the primary effect stated first and the caution second — good front-loading and no redundant restatement of the title. 'Hands the task back to you' is slightly colloquial for an operational contract, but it is not wasted text.

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

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

For a one-parameter, non-destructive activation tool with no output schema, the description covers the important unknowns: what starts, what keeps happening, and the confirmation question. It is thin on the immediate return value and on how activation relates to trigger_resume, which are the only notable gaps.

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 already documents that draft_id comes from trigger_draft. The description adds no further meaning about the parameter (format, validity, or what happens with a stale id), so baseline 3 applies.

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

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

The description uses a concrete verb-plus-resource framing ('Turn a draft on') and explains the immediate consequence ('its probe starts running on schedule'). It implicitly distinguishes itself from trigger_pause/trigger_resume by scoping the input to a draft, but it never names a sibling tool to contrast with, so an agent must infer the draft-vs-existing-trigger distinction.

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

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

It gives a real precondition for use: the trigger becomes autonomous, so 'decide first whether the user should confirm it.' The escape hatch is delegated to an external skill ('the self-starter:triggers skill says when to ask') rather than stated inline, which leaves the actual condition unstated in the description 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 flag destructiveHint=true and readOnlyHint=false, so the description is not carrying the safety burden alone. It still adds real context beyond them: exactly what is destroyed (probe code, state) and what is preserved (past fire history), which is what an agent needs before an irreversible call.

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

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

Two sentences, zero padding, with the core action front-loaded and the scope/consequence detail following immediately. Nothing could be cut without losing meaning.

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

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

For a single-parameter destructive tool with a fully described schema and no output schema, the description covers action, collateral damage, and data retention. Only irreversibility confirmation expectations are unstated, 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 trigger_id description already points to trigger_list as the source of valid ids. The tool description adds nothing further about the parameter, 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?

Specific verb+resource ('Delete a trigger') with an added scope clause naming the collateral ('its probe code and its state'). The verb alone differentiates it from trigger_pause/trigger_resume/trigger_draft among siblings, though no sibling is named explicitly.

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

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

Usage is implied by the destructive verb and the note that history survives, which hints at the delete-vs-pause tradeoff, but the description never states when to choose trigger_delete over trigger_pause or trigger_draft, nor any prerequisites or confirmation requirements.

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

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

Goes well past the annotations by describing the actual pipeline: the engine validates the definition, saves the probe code, and runs the probe exactly once. It discloses what is returned (draft id, trial run result, warnings, plain-language description) and the key safety property that nothing is scheduled until activation, which the destructiveHint/readOnlyHint flags alone would not convey.

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

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

Front-loaded with the core action, then the side effects, then the return values, then the alternatives and authoring reference. Four tight sentences with no filler, though the return-value enumeration and the skill pointer could be trimmed slightly without loss.

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 nested-object, no-output-schema mutation tool, the description supplies everything an agent needs: what it writes, that the probe executes once against the live user permission context (echoed in the code param), the returned artifacts, and the activation gate. The absence of an output schema is compensated by the explicit return list.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the mutual-exclusivity rule the schema only implies piecemeal: pass either code you wrote or a recipe, not both. That is a genuine constraint that helps the agent construct a valid call, though it does not elaborate on definition sub-fields beyond pointing at the skill.

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 ('Submit a new trigger, or a new version of one, as a draft') and immediately scopes it against the sibling that actually runs things ('Nothing runs on a schedule until trigger_activate'). An agent can separate this from trigger_activate and trigger_recipes without opening any schema.

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

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

Gives clear context for when to use it: drafting rather than activating, and choosing between hand-written code and a ready-made recipe from trigger_recipes. It also points at the self-starter:triggers skill for authoring the definition. The one missing distinction is against the sibling trigger_update, which is not mentioned even though the 'replace' parameter overlaps with 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description goes beyond that by disclosing the composition of the response (definition, firing-rule state, recent checks, recent fires), which is genuinely useful since no output schema exists. It stops short of noting behavior for an unknown/invalid trigger_id or any limits on 'recent'.

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

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

Two tightly written sentences with the returned content front-loaded and the purpose second. The parenthetical examples ('waiting, cooling down, ...') clarify the state concept in a few words with 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 single-parameter read tool with full annotation coverage, the description is nearly sufficient: it explains what the agent gets back and why it would call it. The only gaps are edge behavior (invalid id, empty trigger) and how far back 'recent' extends, which are minor for this complexity.

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%, with the schema itself telling the agent the id comes from trigger_list. The description adds no format, example, or lookup guidance beyond that, 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?

States a specific verb+resource ('Details of one trigger') and enumerates what the detail comprises: definition, firing-rule state (waiting, cooling down), recent checks, recent fires. The singular 'one trigger' plus the schema's reference to trigger_list makes it distinguishable from the list/history siblings without opening either schema.

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

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

Gives an explicit diagnostic use case: 'Use it to explain why a trigger did or did not fire.' That is a clear when-to-use signal, but it names no alternatives or exclusions — e.g. when to prefer trigger_history for raw events or trigger_list for discovery — leaving sibling routing partly to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context beyond those annotations: the result ordering (newest first), the grading information returned per fire, and the fact that omitting the id broadens scope to all triggers. It says nothing about retention window or result volume, but with annotations carrying the safety profile this is solid.

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 what you get and how it is ordered, followed by the scoping rule. No filler. The phrase "with how each was handled and the receipt" is slightly compressed jargon but stays within budget.

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 listing tool with no output schema, the description covers ordering, per-fire contents, and the optional-filter behavior, which is the information an agent needs to call it correctly. Gaps are minor: no retention window, and "receipt" is never explained, leaving the exact return payload partly opaque.

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

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

Schema coverage is 100%, so both parameters are already documented, which sets a baseline of 3. The description adds meaning the schema does not: omitting the optional trigger_id is defined as "all triggers" rather than an error or empty result, and it cross-references trigger_list as the source of ids. Limit behavior is left entirely to the schema.

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

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

The description identifies a concrete resource (recent fires, i.e. trigger executions) and states the ordering (newest first) plus the payload shape (how each was handled and the receipt). It is clear what the tool returns, but it never distinguishes itself from plausible siblings such as trigger_report or trigger_get, which could also surface execution information.

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: "Recent fires" signals this is for reviewing past executions, and "Leave out trigger_id to see all triggers" gives a scoping rule. There is no explicit when-to-use statement, no mention of when to prefer trigger_report or trigger_get, and no note about how far back the history goes.

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 supplied annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered without the description's help. The description does add real value beyond that by enumerating the response fields, but says nothing about ordering, pagination, or behavior when no triggers exist.

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

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

A single front-loaded sentence with no filler; every clause maps to a distinct piece of returned data. There is no repetition of the title or annotations.

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

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

For a no-argument read-only listing tool with full annotation coverage, the definition is close to sufficient, and the field list compensates for the absence of an output schema. Ordering and empty-result behavior are the only notable omissions, and both are minor at this complexity.

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 nothing for the description to disambiguate and the baseline applies. No parameter-level detail is expected or missing.

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 all triggers") and names the fields returned (state, last check, next check, number of fires), so the agent knows exactly what the call produces. It stops short of distinguishing itself from siblings such as trigger_get or trigger_history, which also surface trigger data.

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 explicit when-to-use guidance and no mention of alternatives, even though trigger_get, trigger_history, and trigger_report are close siblings. The only steer is the word "all", which weakly implies a bulk-listing use case rather than a single-record lookup.

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

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

Annotations already declare destructiveHint=false and readOnlyHint=false, so the bar is lower, and the description adds real substance: the probe stops running and the state is reversible via resume. It stays silent on what happens to in-flight or queued runs and on any permission requirements, which are the remaining behavioral gaps.

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

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

One short sentence, front-loaded with the verb, effect, and reversal condition. No filler or restatement of the title.

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

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

For a one-parameter, non-destructive state-change tool with no output schema, the description covers the essential what and the reversibility. Only edge-case behavior for running or queued executions is left undocumented.

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, and the schema itself points to trigger_list as the source of the id. The description adds nothing about the parameter, which is acceptable at full coverage but earns no bonus.

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 (pause) and resource (trigger) plus the operational meaning — the probe stops running. It gestures at trigger_resume with 'until it is resumed' but never names that sibling or any other, so differentiation is implied 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?

Usage is implied by the effect: pause when you want a trigger's probe to stop while keeping it resumable. There is no explicit when-to-use versus when-to-delete, when-not-to-pause, or named alternative such as trigger_resume or trigger_deactivate, leaving the agent to infer routing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds real value beyond that by disclosing what each returned item contains: parameters, required secrets, and setup steps. It does not mention result count or sizing, which keeps it off a 5.

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

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

Three short sentences, front-loaded with the action and resource, with no filler. The usage hint is efficiently placed at the end where it reads as a closing recommendation rather than padding.

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

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

For a zero-parameter list tool with no output schema, the description adequately explains what comes back (parameters, secrets to store, setup steps) so an agent knows the shape of results. A brief note on how many recipes are typical or what to do next after listing would make it complete.

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

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

The tool takes zero parameters (schema coverage 100% trivially), so the baseline is 4. Nothing in the description introduces confusing or undocumented inputs.

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 ("List the ready-made recipes") and immediately defines what a recipe is ("probes that ship with the plugin"). It clearly separates this from trigger_list/trigger_get by framing recipes as pre-built templates rather than user-created triggers, though it never names a 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?

"Prefer a recipe when one fits" gives an explicit selection heuristic favoring this tool when a pre-built template matches the need. It stops short of naming the alternative (e.g. building a trigger manually via trigger_draft) or stating when NOT to use it, so it falls just below the top score.

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

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

Annotations already cover readOnly=false, destructive=false, and openWorld=false, so the safety profile is set; the description adds real behavioral context beyond that: one call per fire, at the end, and that notify=true causes a user-facing notification now. It stops short of saying what happens to the summary (where it surfaces) or whether reporting 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?

A single front-loaded sentence with the action first and the how-to details trailing, and every clause carries information (one call per fire, timing, all three parameters). Nothing is redundant with the schema or annotations.

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

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

Small three-parameter tool with no output schema, and the description covers purpose, timing, all parameter usage, and the notification side effect. An agent has everything needed to call it correctly on the first try.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning: the summary is constrained to 'one line', fire_id comes from the [self-starter] message, and notify should be true only when the user should be told now. This sharpens the schema's terser wording rather than repeating 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?

Specific verb and resource: 'Report that you finished handling a trigger fire', and it defines what a fire is ('a message that starts with [self-starter]'), a concept no sibling tool explains. An agent can distinguish this from trigger_history or trigger_get without opening the schema.

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

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

Gives explicit timing and frequency: 'Call it once per fire, at the end', which directly answers when to invoke it. It does not name an alternative or a when-not condition, but the sibling set offers no competing 'report completion' tool, so the gap is minor.

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=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds one useful behavioral fact beyond that: the probe runs again immediately, signaling a prompt side effect. It omits what happens if the trigger is not currently paused and whether the call 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?

Two short sentences with zero waste, purpose front-loaded before the behavioral note. Nothing could be removed without losing 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 one-parameter, non-destructive mutation with annotations and no output schema, the description covers purpose and immediate effect adequately. The main residual gap is the relationship to trigger_activate, which matters given the sibling list.

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

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

Schema description coverage is 100% and the single trigger_id parameter is documented with a pointer to trigger_list. The description adds no further meaning about the identifier, 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?

States a specific verb and resource ('Resume a paused trigger'), which is clearly distinct from trigger_pause. It does not, however, distinguish itself from sibling trigger_activate, which an agent could reasonably confuse with resume.

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 'a paused trigger' implies the precondition for use, but there is no explicit when-not guidance and no routing to trigger_activate or trigger_draft, which is the main ambiguity in this sibling set.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is largely covered. The description still earns credit by clarifying that the probe neither fires the trigger nor mutates it, which matters because openWorldHint implies an external call that could plausibly have side effects. It does not mention latency, external-service failure modes, or whether repeated probes consume quota.

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

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

A single front-loaded sentence with no filler; the action, the one-shot scope and the non-mutating guarantee all appear before any trailing detail.

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 full annotation coverage, the definition covers what it does and what it will not do. The gap is 'show the result' — with no output schema, the shape of a probe result (pass/fail, latency, error detail) is left entirely undefined.

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 trigger_id field already documents that the id comes from trigger_list, so the schema does the heavy lifting. The description adds only the qualifier that the referenced trigger must be active, which is a small but real constraint 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 ('Run an active trigger's probe') plus the scope 'once now', which separates it from trigger_get (read config), trigger_activate (change state) and trigger_tune (adjust settings). An agent can tell from the sentence alone what this does and that it is a one-shot execution rather than a listing or mutation.

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

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

Gives clear usage context ('once now' and 'without firing or changing anything') and an implicit precondition that the trigger must already be active, which steers the agent toward trigger_activate first. It never names an alternative sibling explicitly, so the routing logic has to be inferred rather than read.

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

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

Goes well past annotations (which only say non-read-only, non-destructive) by disclosing the stateful semantics — no new baseline and no re-fire for an already-holding condition — plus the side effect that the user is told what changed and why. The monotonic tightening constraint is established as a behavior, not just a schema rule.

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

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

Front-loaded with the core action and state guarantee, then the allowed levers, then the exclusion — a sensible order with no filler sentences. The opening is dense and parenthetical-heavy, bordering on a run-on, which costs a point.

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 7-parameter mutation with no output schema, the definition covers scope, direction of change, state preservation and user-visible consequences, which is what an agent needs to invoke it correctly. Return behavior and failure modes (e.g. a trigger already paused) are left unstated but are low stakes 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 coverage is 100%, so the baseline is 3; the description earns a step up by enumerating the five levers in plain language and framing the one-directional constraint ('check less often, wait longer ... allow fewer fires') as a deliberate safety principle rather than an isolated per-field note. It does not add format details beyond what the schema already 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?

Specific verb phrase ('Make a trigger ... quieter') plus resource and the exact dimension of change (check interval, cooldown, hold time, fire cap, pause). It explicitly draws the boundary against trigger_update, so an agent can distinguish it from siblings without opening schemas.

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

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

Strong when-to-use ('the one change allowed while handling a fire, and then only for the trigger that fired') and an explicit when-not with the alternative named ('anything that makes a trigger more sensitive goes through the user and trigger_update'). The gap is the 'pause' option, which overlaps the sibling trigger_pause and is never routed or differentiated.

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=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior beyond that: changes are applied immediately and firing rules restart, which materially affects how an agent should sequence calls. It stops short of describing validation failures, partial-apply behavior, or auth requirements, so it is strong but 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?

Three sentences, front-loaded with the action and the changeable fields, then the effect, then the routing rule. The field list is dense but each item earns its place as valid targets. Minor cost: the long comma-separated enumeration is harder to scan than a short structural hint would be.

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 nested objects, the description covers what can change, when changes take effect, and where to go for the excluded cases. With full schema coverage and no output schema, little is missing. It could still say whether a call is atomic or whether unknown fields are rejected, but nothing an agent needs to invoke it correctly is absent.

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

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

Schema coverage is 100% and the schema already explains the changes object shape and null semantics. The description nonetheless adds value by enumerating which nested paths are legal targets (probe.params, probe.timeout, target.kind/cwd, etc.), which the schema only gestures at with 'shaped like the definition'. It does not go deeper into per-field formats, but the enumeration is a real constraint an agent would otherwise have to guess.

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

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

Opens with a specific verb and resource ('Change an existing trigger') and immediately enumerates the exact fields that can be modified (probe.params, probe.interval, policy, action, target, notify, name, intent). It also explicitly contrasts itself with the sibling trigger_draft, so an agent can distinguish the two without reading either schema.

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

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

States the boundary condition directly: 'To change the probe code or the mode, use trigger_draft with replace=true instead.' This names the alternative tool, the parameter to set, and the exact cases that should be routed elsewhere, leaving nothing to inference.

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