agent-cronjob

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

Goes well beyond the annotations by disclosing the one-time secret exposure ('SHOWN ONCE, store them now') and exactly what subsequent calls return. This is critical, non-obvious behavior for a credential-issuing tool that an agent would otherwise miss, and it is consistent with readOnlyHint=false and idempotentHint=false.

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

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

Front-loads the workflow position and the action, then packs the two highest-value facts — what gets returned and that it is unrecoverable — into a single dense sentence, with the REST mapping as a trailing parenthetical. 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 correctly carries the return-value burden by naming both credentials and the already_issued state. The one gap is the pending case: it never says what the response looks like when the webhook is not yet verified, which matters for a polling tool an agent may call in a loop.

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%: job_id is documented as job_<ULID> from create_job and setup_token as the act_st_… value with the Bearer header alternative. The description only restates that setup_token drives the poll, adding no new syntax or format detail, 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?

Names a specific verb and resource: 'Poll verification state with the setup_token', and adds that the first successful call returns hmac_secret and management_token. This distinguishes it from get_job or verify_challenge by centering on credential collection, though it never names those siblings explicitly, so the boundary is inferred rather than stated.

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

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

The precondition is explicit — 'The first call after the webhook is verified' — and repeat behavior is covered ('later calls say credentials: already_issued'), which tells an agent it is safe to poll. It stops short of naming an alternative tool for the pre-verification case (e.g. verify_challenge), leaving that routing 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 flag readOnlyHint=false and openWorldHint=true, so the description's added value is real: no account or API key needed, a one-time setup_token is returned, no triggers fire until verification, and outgoing_auth secrets are stored encrypted and never shown back. It stops short of stating behavior on repeated calls even though idempotentHint=false, leaving duplicate-job consequences unstated.

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?

Dense but front-loaded: the step number, the no-auth promise, and the return values come first, then the challenge protocol. Nearly every clause carries weight; the trailing "(REST: POST /v1/jobs)" is the only low-value addition.

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

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

For a 14-parameter tool with nested objects and no output schema, the description does explain the important return values and the full handshake sequence. But half the configuration surface (retry and catchup tuning) is left entirely to undocumented schema fields, so an agent cannot reason about those knobs from the definition.

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 50% with 14 parameters, and seven top-level params (name, timeout_ms, catchup_policy, catchup_window_sec, retry_base_sec, retry_max_attempts, retry_max_backoff_sec) have no description in the schema and no mention in the description. Only webhook_url, the schedule forms, verification_mode, and signature_in_body get any narrative treatment, so the description does little to close the coverage gap.

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 ("Register your webhook and schedule" → creates a job) and goes further by naming the exact outputs (job_id, setup_token) and the side effect (POSTs a url_verification challenge). It is unambiguously distinguishable from siblings like get_job or update_job because it is framed as "Step 1" of a registration flow.

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

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

It explicitly routes the agent: answer the challenge by echoing (then call claim_credentials) or reply 2xx and call verify_challenge (callback), and it warns that nothing triggers before verification. This is a clear when-to-use-which-sibling map with a stated precondition, not just implied context.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description still earns credit for disclosing behavior the annotations do not: that all credentials are revoked and the action is irreversible. It does not cover auth errors or behavior on a missing job, which keeps it at 4.

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 its consequence, with the REST endpoint in parentheses as a trailing reference. No filler; the only debatable element is the endpoint annotation, which some agents will find useful for cross-checking.

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 destructive tool with full annotation and schema coverage, the description supplies what structured data cannot: irreversibility and credential revocation. It leaves open what happens to existing deliveries/runs and how failures surface, but nothing essential to invoking it 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%, and the schema already explains job_id format and the optional management_token/Authorization fallback. The description adds no parameter-level meaning, so the baseline of 3 applies.

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

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

The description uses a specific verb+resource ('Stop the job forever') and adds the consequential side effect ('revoke all its credentials'). The word 'forever' implicitly separates it from pause_job/resume_job, though it never names those siblings explicitly, which keeps it just short of a 5.

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

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

Caution is implied by 'Cannot be undone,' and 'forever' hints at the pause_job alternative, but there is no explicit when-to-use/when-not guidance or named alternative. The agent must infer that this is the terminal option in the pause/resume/delete family.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description's job is to add context — and it does: newest-first ordering, the exact fields per run (scheduled_at, first attempt, delay, attempts, status, last response code), and that since/until filter on scheduled_at rather than completion time. It doesn't mention retention limits or the default/max page size, which keeps it from 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?

Compact and front-loaded — the returned fields, then filter semantics, then pagination. The trailing REST endpoint note (GET /v1/jobs/{id}/runs) adds little for an MCP caller and is the one expendable element.

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, listing the per-run fields is genuinely necessary and is present, and the date-filter and pagination behavior is covered. Gaps remain on the status filter and limit bounds, and the cursor/next_cursor naming mismatch leaves a small ambiguity for a 7-parameter tool.

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

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

Schema coverage is only 29%, so the description has to carry weight: it clarifies that since/until are ISO 8601 and apply to scheduled_at, and that paging uses a cursor. However, the 'limit' and 'status' filter parameters are never explained, and it calls the paging token 'next_cursor' while the actual parameter is named 'cursor', which risks confusion about what to pass back.

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?

Opening phrase 'Trigger log, newest first' plus the enumerated fields makes clear this returns the run history for a job, distinguishing it from the single-run sibling get_run (though it never names that sibling). The specific resource (runs of a job) and the ordering are both stated explicitly, so an agent knows what it gets.

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 data described (paginated run history with date filters), but there is no explicit when-to-use/when-not guidance and no reference to get_run or get_stats as alternatives. The agent must infer that this is the bulk-history tool while get_run fetches one run.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description still adds genuine context beyond them: the webhook path is masked and credentials are returned only as prefixes, which tells the agent the payload is deliberately redacted. It does not discuss auth behavior beyond what the schema says.

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 listing the returned fields, plus a compact REST route reference in parentheses. No filler and no repetition of the schema.

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

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

For a simple read tool with full annotations, full schema coverage, and no output schema, the description usefully summarizes the return payload and its redaction behavior. Only the missing guidance on when to choose this over get_run, get_deliveries, or list_jobs keeps it from being complete.

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

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

Schema description coverage is 100%, and the job_id format (job_<ULID> from create_job) and the optional management_token fallback are fully documented in the schema. The description adds no parameter-level information, 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 enumerates exactly what is returned for a single job (settings, status, next_run_at, run_count, credential prefixes) and the phrase 'of one job' implicitly separates it from list_jobs. It stops short of an explicit retrieval verb or naming a sibling, so it is clear but not maximally 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?

There is no when-to-use guidance: nothing says to call this after create_job, or to prefer get_run/get_deliveries for execution history or list_jobs for enumeration. The agent must infer the context from the sibling names alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine value by disclosing the payload contents (timing, status, error, next retry), but says nothing about authentication needs, pagination of attempts, or behavior when the run is still in flight.

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

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

Two compact clauses: the returned content first, the REST endpoint second. Every element earns its place, though the sentence is a fragment rather than a full statement of purpose.

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

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

With no output schema, the field enumeration is the main carrier of return-value information, which is helpful. However, for a 3-parameter tool with one undocumented parameter and no mention of auth or error cases, the description leaves real gaps an agent would want closed.

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

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

Schema coverage is 67%: job_id carries a format hint ('job_<ULID> returned by create_job') and management_token documents the Authorization-header fallback, but run_id has no schema description. The description's REST path template (GET /v1/jobs/{id}/runs/{run_id}) only implies how the two IDs relate, adding little beyond the schema.

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

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

The description names the resource ('one run') and its sub-resource ('each delivery attempt') and enumerates the fields returned (sent_at, response status, duration, error, next retry), so an agent knows this is a single-run detail read. It does not distinguish itself from the sibling get_deliveries, which likely overlaps in the delivery-attempt data, so it stops 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?

There is no guidance on when to use this tool versus get_deliveries, get_job, or list_jobs. The agent must infer that this is the drill-down for a single run, and nothing states prerequisites or exclusions.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds useful context beyond that: the default window is 24h and the response contains aggregate punctuality metrics rather than raw records. It says nothing about cost, latency, or how the aggregates behave for jobs with no runs, so 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?

A single front-loaded sentence listing the metrics and default, followed by a compact REST mapping. Nothing is padded, though the parenthetical REST hint is low value for an MCP caller.

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 burden of explaining return values and does so by naming the metrics. Missing details are minor: units and formatting for p50/p95 delay and whether the response includes the effective window used.

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

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

Schema coverage is 67%: job_id and management_token are documented in the schema, but the window enum carries no per-value description. The description compensates by stating the default window is 24h, which is genuinely new meaning. It adds nothing about the effect of window on aggregation granularity or token requirements beyond what the schema states.

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

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

The description names the exact metrics returned (on-time rate, p50/p95 first-attempt delay, success rate) and scopes them to a job over a window, which is far more informative than the name 'get_stats' alone and separates it from get_job, get_run, and get_deliveries. It doesn't explicitly say 'for a given job', but the REST path '/v1/jobs/{id}/stats' and the required job_id make the target 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?

There is no statement of when to choose this over get_deliveries, get_run, or get_job, nor any prerequisite or exclusion. An agent must infer that 'get_stats' is for aggregate performance metrics rather than per-delivery detail purely from the metric names.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered; the description adds the non-obvious behavioral fact that there are no accounts and that a missing management_token falls back to the Authorization header. It does not disclose what happens when one token in the batch is invalid (whole-call failure vs. per-job error), which is the main unstated trait of a batched read.

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

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

Two sentences, front-loaded with the result and followed by the calling mechanics; nothing is padded. The trailing REST endpoint note is mildly redundant with the endpoint bar but does not bloat the 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?

With no output schema, the description should carry the burden of describing what comes back, but it only says "Status of every job" without indicating fields, ordering, or how per-job failures are represented. It covers the inputs and auth adequately, leaving the return contract thin for a batched 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?

There is effectively one top-level parameter whose item fields are already documented in the schema (job_id as job_<ULID> from create_job, management_token as act_mt_… with the header fallback). The description's "up to 20" and header fallback largely restate maxItems and the schema text, adding little new meaning beyond the auth framing.

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?

"Status of every job you hold a management token for" states the resource and the read intent, and the batching mechanism (one pair per job, up to 20) makes clear this is a multi-job fetch rather than a single lookup. It never names the singular sibling get_job, so an agent must infer the batch-vs-single distinction from the parameter shape alone.

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 explains the authentication model ("There are no accounts", per-pair tokens, Authorization header fallback), which is genuine usage context for calling it correctly. It gives no explicit when-to-use vs. get_job/get_stats guidance and no exclusions, so routing between the list and single-job siblings remains implied.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the description repeating "idempotent" earns no credit. It does add genuinely new behavioral context: the schedule-miss consequence after resume and the underlying REST endpoint, which helps an agent reason about side effects.

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

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

Two short sentences with the core effect front-loaded, followed by the most decision-relevant caveat and the endpoint in parentheses. Every clause carries information and nothing is padded.

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, non-destructive, idempotent mutation with fully documented schema and no output schema, the description covers effect and consequence adequately. It could note whether in-flight runs are terminated, but annotations and schema already carry the safety profile.

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 (job_id format, management_token fallback) are fully documented in the schema, so the baseline of 3 applies. The description adds no additional meaning about job_id or the token beyond what the schema already states.

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?

"Stop triggering" is a specific verb-plus-effect phrase and the title names the resource, so an agent can tell this pauses a job rather than deleting it. It stops short of naming the resume_job sibling, leaving the reversibility contrast implicit.

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

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

The clause about schedule points not being made up later gives real context for deciding whether pausing is acceptable. However, there is no explicit when-to-use guidance and no mention of resume_job or delete_job as alternatives for the same need.

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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds two meaningful behavior details beyond that: resuming occurs at the next schedule point, and consecutive_failures is reset as a side effect. It does not discuss authorization requirements or error behavior for invalid states.

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

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

A single compact sentence front-loads the action and preconditions, with the REST endpoint in parentheses as a terse aside. No wasted wording.

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

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

For a simple two-parameter state-transition tool with annotations and full schema coverage, the description covers purpose, precondition, and the key side effect. It lacks detail on failure modes (e.g. resuming a job that isn't paused), which would round it out.

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 job_id and management_token both documented in the schema including format hints and the Authorization bearer alternative. The description adds nothing about parameters, so the baseline of 3 applies with the schema doing the heavy lifting.

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 plus the precondition state: 'Resume a paused or disabled job from its next schedule point'. This clearly distinguishes it from siblings like pause_job, delete_job, and update_job without needing to name them.

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 clear guidance on when to use it (jobs in paused or disabled state) and what the effect is. It doesn't say what happens if the job is running or completed, nor does it explicitly route to an alternative tool, so it falls short of full when/when-not guidance.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description only needs to add context — and it does: prior challenge is invalidated ('The previous challenge stops working') and the rate limit / attempt cap. It stops short of saying what the caller receives back (new challenge payload? expiry?), which matters since there is no output schema.

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

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

Two compact sentences: the action and its invalidation side effect first, then the attempt/interval limits, followed by the REST mapping. Nothing is redundant or buried, and the constraint most likely to cause a failed call 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 2-parameter mutation tool with full schema coverage and annotations, the description supplies the key behavioral facts an agent needs to avoid misuse (invalidation, attempt cap, spacing). The only gap is the return value, which is a modest omission given no output schema exists.

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

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

Schema description coverage is 100%, including the job_id format and the setup_token Bearer fallback, so the description adds no parameter meaning and does not need to. Baseline 3 applies since the schema carries the full load.

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

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

The description names a specific verb and resource — 'Re-send a fresh url_verification challenge to your webhook' — which clearly distinguishes it from verify_challenge (validating one) rather than just restating the title. It lacks an explicit sibling callout ('use X instead when...'), which keeps it just below 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?

Practical invocation constraints are stated (max 5 re-sends, at least 60 s apart), which implicitly tells the agent this is a recovery action for a lost or stale challenge. However, no explicit when-to-use vs. verify_challenge or when-not-to-use guidance is given, leaving the agent to infer the recovery scenario.

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

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

Beyond destructiveHint=true and idempotentHint=false, the description discloses the two things an agent most needs: the secret is returned once and must be stored immediately, and existing triggers emit two v1= signatures (new first) until previous.expires_at. That is real consequence-level disclosure the annotations cannot carry.

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

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

Two dense clauses, no filler, and the irreversible part (shown once) comes first. The middle clause about previous.expires_at and dual signatures is telegraphic enough to require a second read, which costs it 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 destructive, non-idempotent mutation with no output schema, the description covers return-value handling, backward compatibility during grace, and the endpoint. Missing only authorization/rate-limit notes and what happens to the old secret after the grace window expires.

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

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

Schema coverage is 67% — job_id and management_token are documented in the schema, but grace_sec has no schema description at all. The description compensates by explaining grace_sec as the window controlling previous.expires_at and giving its 24-hour default, which is meaningfully more than the schema offers.

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 front-loads the outcome — a new hmac_secret — which makes the rotation effect concrete, and the title/name supply the verb+resource. It does not, however, distinguish this from the sibling rotate_token, which rotates a different credential; an agent must infer the difference from the secret name alone.

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 statement of when to call this versus rotate_token, nor any prerequisite guidance. The grace-window detail implies an operational context (rolling deployment) but never says when rotation is warranted or discouraged.

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

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

Beyond the destructive and non-idempotent annotations, it warns that the new token is shown only once and must be stored immediately. It also precisely discloses the old token's invalidation behavior, including that the default grace period of zero revokes it immediately.

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

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

The description is compact and front-loads the most critical warning about one-time token visibility. Invalidation timing and the REST route follow without filler or redundant explanation.

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 sensitive mutation with no output schema, it supplies the essential result-handling warning and old-token lifecycle behavior, while the schema covers identification and authentication. Explicit selection guidance versus rotate_secret and advice on choosing a grace period would make it more complete.

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

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

The schema documents job_id and management_token but leaves grace_sec without a description. The description compensates directly by explaining that grace_sec controls how long the old token remains valid and that its default of 0 means immediate invalidation.

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?

Together with the name and title, the description clearly concerns replacing a job's management token: a new token is issued and the old one stops working. It does not explicitly differentiate this operation from the sibling rotate_secret tool.

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 rotation context implies using the tool when a management token must be replaced, and the grace-period detail helps inform that decision. However, there is no explicit when-to-use guidance, prerequisite, or comparison with rotate_secret.

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

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

Annotations already establish it as a non-destructive idempotent write, and the description adds real behavior beyond them: the change applies from the next attempt, raising max_runs on a completed job reactivates it with next run = next occurrence after now and no catch-up, and it returns the updated job. This is exactly the deferred-effect and side-effect detail an agent needs before mutating.

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 operation and its two mutable fields, with consequences trailing in parentheses; every clause carries information. The nested parenthetical is dense enough to read as one long sentence, but nothing is redundant.

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 4-parameter mutation with no output schema, it discloses return value ('the updated job'), timing of effects, and reactivation semantics. Minor gaps remain, such as what happens when neither optional field is supplied, but nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: signature_in_body takes effect from the next delivery, and max_runs increases can reactivate a completed job. Those timing and state-transition semantics go beyond the parameter docstrings.

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

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

States a specific verb and resource ('Change a job in place') and enumerates the exact mutable fields (signature_in_body and/or max_runs), plus the REST route. It partially distinguishes from siblings by noting 'there is no separate resume for completed jobs', which routes the agent away from resume_job, though it never names pause_job/resume_job explicitly for the non-completed case.

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

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

Gives concrete conditions for each field: use signature_in_body when the platform drops X-Cronjob-* headers, and raise max_runs when a job is stalled at max_runs_reached. It implicitly excludes the resume path, but stops short of naming the alternative tool the agent should pick for a merely paused job.

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 the mutation/safety profile (readOnly=false, idempotent=false), and the description adds the critical behavioral fact that the response yields hmac_secret and management_token shown only once, with an instruction to store them. It omits failure behavior and what happens if verification is repeated, which matters given idempotentHint=false.

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

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

Three short, front-loaded clauses with no filler; the one-shot secret warning is correctly placed before the REST cross-reference, which is secondary 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 two-parameter step tool with no output schema, the description supplies the step position, the required input source, and the most important return-value consequence (one-time secrets). Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented, including the job_<ULID> format. The description merely restates that the challenge comes from the webhook, adding negligible meaning 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 action (send back the challenge value) and its position in the flow ('Step 2 (callback mode)'), plus the REST endpoint. It is clearly distinct from create_job and retry_challenge, 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?

'Step 2 (callback mode)' implies when in the workflow it applies and that a callback/webhook has already been received, but there is no explicit when-not guidance and no routing to alternatives such as retry_challenge when the challenge is lost or expired.

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