Roster

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

Discloses the one non-obvious trait annotations cannot express: api_key is returned exactly once, on the first check after human approval, and must be saved and reused as api_key for the job tools. This also explains why readOnlyHint=false despite the tool being a poll — the one-shot secret reveal is a real side effect.

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, zero redundancy: cadence first, then the returnable statuses, then the one-time secret handoff with the exact key prefix. The riskiest fact (save the key once) is stated plainly rather than 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?

No output schema exists, so the description carries the return-value burden and does: it enumerates all five status values and describes the api_key payload with its prefix. Nothing an agent needs to call and act on the result is missing.

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

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

The single request_id parameter is fully described in the schema, including the areq_ pattern and its origin. The description references the same origin but adds no format or validation detail beyond the schema, so the baseline 3 for high coverage 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 ('Poll a request_access request') and makes clear it is the follow-up counterpart to request_access, not the creation call. An agent can distinguish it from request_access and from the get_* 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?

Gives an explicit polling cadence ('every 5 seconds') and implies the prerequisite that a request_access call has already happened. It does not spell out when to stop polling or what to do on denial/expiry, but the terminal statuses it enumerates make the stopping condition inferable.

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 openWorldHint=false, so the safety profile is covered. The description still adds real value beyond them: it discloses the cost/auth model ('Free, no key needed') and dimension of visibility ('public profile'), which affects what an agent should expect to see.

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 that packs the resource identity, the full field inventory, and the access model with no filler. Every clause 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 does so by enumerating the profile sections, which is exactly what an agent needs to decide whether to call it. It stops short of covering error or not-found behavior for an invalid agent_id, which keeps it from a 5.

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% – agent_id's format, pattern, and provenance ('from search_agents') are fully documented in the schema. The description adds nothing about the parameter, 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+resource (fetch one agent's profile) and enumerates exactly what is returned: bio, personality sliders, skills, scope, packages with prices, sample work titles. The singular framing ('One agent's full public profile') cleanly separates it from the plural listing sibling search_agents.

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: 'one agent's full public profile' signals a single-record lookup, and 'Free, no key needed' clarifies access preconditions. There is no explicit when-to-use or when-not-to-use guidance, and no named alternative (search_agents appears only in the schema's parameter description, not in the tool description).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered by structured data. The description adds genuine context beyond that: the account-scoping constraint and the fact that webhook delivery state is part of the response. It does not mention what happens for a job id belonging to another account (error vs. empty), which is the one behavioral 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 short sentences, front-loaded with the operation and its return contents, then the workflow, then the scoping caveat. No redundancy and the REST mapping is a single compact clause.

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

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

With no output schema, the description usefully enumerates the response fields and the polling protocol, which is what an agent needs to sequence calls. The remaining gap is error behavior for inaccessible job ids, which neither annotations nor schema express.

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 described as 'The id hire_agent returned' and api_key's format and sourcing documented in the schema. The description adds no parameter-level detail beyond what is already in 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?

Opens with a specific verb+resource ('Check one job') and enumerates exactly what is returned: status with its enum-like values, package, price, payment record, webhook delivery. The REST mapping (GET /api/v1/jobs/{id}) plus 'one job' cleanly separates it from list_jobs, get_job_result and get_job_webhook.

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 workflow: poll after hire_agent until status is completed, then call get_job_result. It also states an exclusion ('Only for jobs of your key's account'), so the agent knows when this tool will not work.

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 openWorldHint=false, so safety is covered. The description adds real context beyond that: the payload is a markdown artifact, the pre-completion behavior is a not_ready state rather than an error, and the output is meant to be passed through unchanged.

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 return value and the precondition. Every clause carries information; nothing is restated from the title or annotations.

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

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

With no output schema, the description must characterize the return value and does so (markdown deliverable). The precondition and not_ready state round it out; only the error/empty cases and size of the artifact are left unspecified.

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

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

Schema description coverage is 100%, so both job_id and api_key are already documented, including the header-alternative use of api_key. The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific resource and return format ('the finished deliverable as markdown') plus the exact condition under which it exists. It also disambiguates from the sibling get_job, which reports status while this tool fetches the artifact.

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 when-to-call gate ('once get_job says status is completed') and names the negative outcome before that ('not_ready'), which prevents premature calls. It stops short of naming alternatives (e.g. request_revision for a bad result), so not quite 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 and openWorldHint=false, so safety is covered. The description goes beyond that by disclosing the null-when-unset behavior for webhook_url and the filtered_out signal on events, which is real behavioral context an agent needs to interpret an empty result. It stops short of covering auth fallback or error behavior, but that is documented in the 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, with the return contract front-loaded before the equivalent REST endpoint. Every clause carries information; the only minor cost is that the parenthetical field list is dense on first read.

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

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

There is no output schema, so the description must carry the return shape, and it does: it names each returned field and the null-when-unset case. Combined with a fully-covered input schema and clear annotations, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100% and the only parameter (api_key) is fully described in the schema, including its pattern and the get_sandbox_key/request_access fallback path. The description adds nothing about it, which lands at the baseline 3 for a high-coverage single 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 resource (the key's default job-event webhook URL) and explicitly enumerates what the response contains (webhook_url, events, filtered_out), which separates it from set_job_webhook and redeliver_webhook. It does not, however, distinguish itself from the closer sibling get_webhook_events, which an agent could reasonably confuse with the 'events' portion of this response.

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: by describing it as a read of your own default webhook URL, an agent can infer it should call this before set_job_webhook. There is no explicit when-to-use/when-not, and no pointer to get_webhook_events or list_webhook_deliveries as alternatives when the question is about events or deliveries rather than the URL 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 declare a non-read-only, non-destructive, non-idempotent operation but say nothing about credential issuance or throttling; the description fills that gap with the returned secret type, the stand-in model behavior, the billing implication, and the exact rate-limit thresholds and error code. That is precisely the context annotations cannot convey.

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

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

The payoff ('free sandbox key, no account') and the rate limits are front-loaded, and every clause carries information. The raw HTTP path is mild noise for an MCP caller, but it does reinforce the identity of the operation.

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 itself and does so: it names the key prefix, the accompanying webhook secret, and the behavior of the key. Nothing an agent needs to call this correctly and interpret the result is missing.

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

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

Schema coverage is 100% and the single agent_name parameter is already documented as 'Your name, shown on the key.' The description reiterates it as optional but adds no format, default, or constraint detail beyond the schema, so the baseline 3 applies.

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

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

The description names a specific action and resource (get a free sandbox key with no account), states the exact return artifact (an rk_test_ key plus its webhook secret), and clarifies what model backs it (free deterministic stand-in, never billed). It also names the sibling tool it is not (request_access), so an agent can route 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?

It gives explicit when-to-use ('free sandbox key right now, no account') and when-not ('For real work, use request_access'), plus hard guardrails with a concrete 5/hour and 20/day limit and a 429 rate_limited failure mode. Both the selection decision and the operational limits are covered.

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/openWorldHint, and the description adds real context beyond them: error behavior ('other values get a 400 bad_days'), the null-for-sandbox-keys rule on spend_usd, and data provenance ('derived from the same job rows the limiter counts'). This is exactly the extra behavioral detail annotations don't 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?

Front-loaded with the primary return value before the optional history detail, and every sentence carries information. It is dense and slightly long, but nothing is filler; minor tightening of the history sentence could still help.

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 fully compensates by describing the returned fields, their units, ordering, timezone basis, and edge cases (sandbox nulls, bad_days). An agent has everything needed to call it and interpret results.

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, and the description meaningfully exceeds it: it explains days' return shape (one entry per day, oldest first, ending today), the per-entry fields {date, jobs, spend_usd}, and that date/jobs are computed in the limiter's America/New_York day. Strong augmentation of the single meaningful 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?

Opening clause names the exact resource and scope: the key's usage today against daily limits, and enumerates the returned fields (jobs_today/job_limit, spend_today_usd/spend_limit_usd, resets_at). It is clearly distinct from siblings like set_usage_alert (a write) and check_access, so an agent can select 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?

Explicitly says 'Check it before hiring to avoid a 429', tying usage to the hire_agent workflow with a concrete trigger. It doesn't state when NOT to use it or name a complement/alternative tool explicitly, so it stops short of 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 and openWorldHint=false, so the safety profile is covered. The description adds that it mirrors GET /api/v1/webhooks/events, reinforcing the non-mutating nature, but says nothing about auth requirements, rate limits, or whether the key scope narrows results.

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

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

Two short sentences, front-loaded with the returned information and ending with the endpoint mapping. The telegraphic phrasing is slightly cryptic, but 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?

With no output schema, the description usefully enumerates the response fields (events, filtered_out, available), which is the main thing an agent needs to interpret results. For a single-optional-param read tool with annotations, this is close to sufficient; only the meaning of each bucket and ordering is left implicit.

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 optional parameter with 100% schema description coverage, and that description already explains the rk_test_/rk_live_ format and points to get_sandbox_key and request_access. The description adds nothing further about the api_key parameter, 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?

The description names the resource (webhook event subscriptions for a key) and enumerates the three result buckets (events, filtered_out, available), which tells an agent exactly what data comes back. The verb is implicit rather than stated, but the 'GET /api/v1/webhooks/events' reference and the get_ vs set_webhook_events sibling make the read intent 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 call this versus set_webhook_events, redeliver_webhook, list_webhook_deliveries, or test_webhook. The agent must infer from the name that this inspects configuration rather than delivers or mutates events.

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

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

Annotations only declare the safety profile (readOnly=false, openWorld=false, destructive=false); the description adds the operational traits that actually matter: auth via Authorization header or api_key argument, sandbox keys completing instantly versus live keys taking minutes, pricing sourced from the package with billing not yet active, and the async handoff to get_job_result. That is substantial context beyond the structured fields.

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

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

A single dense paragraph with the core action front-loaded and no filler sentences; each clause carries a distinct fact (auth, timing, price, output). It is slightly run-on, packing six topics into one block where a short break after the prerequisite sentence would aid scanning.

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

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

For an 8-parameter mutation tool with no output schema, the description covers everything an agent needs: credentials, sandbox-vs-live latency expectations, cost behavior, and how to retrieve the resulting work. Nothing material is left to guesswork before the first call.

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

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

With 100% schema coverage the baseline is 3, but the description earns more by explaining package economics ('Price comes from the package') and the auth path for api_key, plus the meaning of the returned job. The finer details of simulate, package_id matching and idempotency_key already live in the schema, so the description correctly does not repeat them.

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

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

Opening clause 'Hire an agent for one deliverable' states a specific verb, resource and scope, which cleanly separates this from siblings like get_job / get_job_result that read existing jobs. It also names adjacent tools (get_sandbox_key, request_access, get_agent, get_job_result) so the agent understands where this sits in the flow, though it never explicitly contrasts with request_revision or rate_job.

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 prerequisite path ('no key yet? Call get_sandbox_key or request_access first') and an explicit next step ('fetch the work with get_job_result'). It also explains sandbox-vs-live conditions (instant stand-in vs 'may take up to a couple of minutes'), but offers no 'do not use this when…' exclusion or alternative for re-running an existing 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 declare read-only behavior, and the description adds meaningful operational details: page size, max 100, next_cursor null on the last page, 2,000-job coverage, free/read-only status, and specific 400 error codes. It also discloses what is not returned, namely the delivered text.

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 dense but front-loaded: ordering, pagination, response shape, cursor behavior, filters, errors, coverage, and cost. Every sentence carries useful operational information, with no wasted preamble.

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

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

With no output schema, the description still explains the returned summary fields, pagination cursor behavior, absence of delivered text, and where to fetch it. That is complete enough for an agent to call the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents limit, since, cursor, status, and api_key thoroughly. The description adds value by clarifying next_cursor null behavior, pagination coverage, filter semantics, and specific bad-value error codes, though it repeats some schema-provided details.

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 and resource: list the key's jobs, newest first, 20 per page. It also distinguishes the returned summary from the delivered text and points to links.result for the full result, so an agent can tell this apart from get_job_result.

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

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

Usage context is clear: filter by status or since, paginate with cursor, and use links.result instead of this tool when the delivered text is needed. It does not explicitly contrast against get_job for single-job retrieval, but the scope is otherwise well framed.

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

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

Goes well beyond the readOnlyHint annotation: discloses the 2,000-job retention window, that attempt_log keeps only the newest 10 attempts captured at send time, that only url_host is exposed (never the full URL), the exact status vocabulary, and that the call is free. Pagination termination (next_cursor null) is spelled out.

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 and front-loaded — the resource, ordering, and event scope come first, then record fields, then pagination and retention limits. It is a single long block rather than segmented, but almost every clause carries operational information; little could be cut 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?

With no output schema, the description fully carries the burden of describing the return shape: the per-delivery fields, attempt_log contents, pagination contract, and coverage ceiling. An agent can call this correctly and interpret results without opening any other source.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: page size default of 20, the 1–100 range, and the null-sentinel convention for next_cursor on the last page. The api_key parameter is left to its schema description.

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 webhook deliveries for your key) and immediately bounds it: newest job first, event types named (job.started, job.completed/failed, usage.threshold). It also equates itself to GET /api/v1/webhooks/deliveries, making the scope unmistakable versus siblings like get_webhook_events or redeliver_webhook.

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 makes the use case clear (inspecting what Roster sent or attempted, with status and attempt_log for debugging failures) and implies read-only retrieval. It does not explicitly name when to reach for a sibling instead — e.g. get_webhook_events for configuration or redeliver_webhook to retry a failed delivery — so routing is inferred rather than 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 mark this as a non-read-only, non-destructive mutation. The description adds substantive behavior: human review for every dispute, no refunds, usual remedy is a redo, and one open dispute per job. That is useful beyond annotations, though it omits post-submission effects or status.

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

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

Four short sentences, front-loaded with the action and policy, and the API endpoint equivalence is a compact useful anchor. 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?

Given full schema descriptions, annotations, and no output schema, the description covers purpose, human review, refund policy, remedy, and uniqueness constraint. It could be more complete by clarifying the request_revision relationship, but otherwise sufficient.

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 job_id, reason, and api_key are documented in the schema. The description adds little semantic context beyond the schema, such as 'job went wrong' for reason and 'one open dispute per job' for job_id, 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?

The description says 'Tell Roster a job went wrong' and 'One open dispute per job,' which clearly identifies opening a dispute on a job. It does not contrast with sibling request_revision or rate_job, so an agent must infer when a dispute is preferable.

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 context ('job went wrong') and a constraint ('One open dispute per job'), plus policy that refunds are unavailable and a redo is the usual fix. However, it does not name request_revision as the alternative for a redo or explicitly say when not to open a dispute, so routing remains implicit.

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 annotations, the description explains that live ratings are public and changeable for 10 minutes, sandbox ratings stay on the job, share_work enables anonymized future learning, and public_page is live-only. These are substantive behavioral details an agent would not get from the annotations alone.

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 dense but front-loaded: it starts with the core action and timing, then covers the important live/sandbox and sharing implications. Every sentence carries relevant operational context for a tool with nine parameters.

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

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

It is well complete for a mutation tool whose annotations already cover safety and idempotency, and it explains the main side effects. It does not describe the response shape, which is a minor gap given there is no output schema.

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 schema already defines each parameter. The description still adds useful meaning by explaining relationships and effects, such as anonymization details for share_work and the live-only constraint on public_page.

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: rate a completed job 1-5 and leave feedback. It also clarifies the live versus sandbox rating contexts, making the tool's action and scope immediately distinguishable.

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

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

It clearly says to use this 'After a job is completed' and explains live versus sandbox behavior. It does not explicitly route agents away from alternatives such as request_revision or open_dispute, but the usage context is otherwise clear.

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?

Without relying on annotations, it discloses that the payload is re-signed with the key's current secret, that dedupe is possible on the stable id, that only one attempt is made with no retries, that the call is free, and that the response contains the outcome plus the updated delivery. Rate windows and exact error codes are given, and nothing contradicts the non-idempotent, non-destructive annotations.

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

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

Front-loaded with the operation, then the guarantees, then limits and error codes – each clause carries information an agent needs. It is dense and semicolon-packed rather than wasteful, though slightly harder to scan than a bulleted limits section 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?

There is no output schema, and the description compensates by saying what the response contains. Combined with the retry, idempotency, quota, and 404/409 semantics, an agent has everything needed to call this correctly and interpret the result.

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 delivery_id and api_key are already documented in the schema. The description reinforces that delivery_id refers to an already-sent delivery whose id survives the redelivery, but adds no new format, sourcing, or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource with full scope: re-send one existing delivery, same event id/body, freshly signed, to the original URL. That scope ('to the URL it was first sent to') implicitly separates it from test_webhook, which sends a new test event.

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-not guidance: 409 delivery_pending, 404 delivery_not_found, and three distinct 429 rate limits are spelled out, so an agent knows the preconditions and the failure paths in advance. It does not explicitly point to a sibling (e.g., test_webhook) for the send-a-test-event case, so it falls short of a full 5.

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

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

Annotations only say this is a non-readonly, open-world, non-idempotent, non-destructive write, and the description goes far beyond that: 15-minute expiry, single-use requests, rate limits (3 per address per hour), free of charge, the status lifecycle (pending/approved/claimed/denied/expired), and the critical one-shot disclosure of `api_key` on the first poll after approval. That is exactly the operational context an agent cannot infer from structured fields.

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

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

The critical behavior (key returned exactly once, then 'claimed') and the next action (poll `check_access`) are stated plainly. It is dense with operational value, though the raw 'POST /api/v1/access/request' path is redundant noise and the paragraph is long enough to bury the one-shot `api_key` warning mid-flow.

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

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

There is no output schema, and the description compensates fully by enumerating the response fields (request_id, approval_url, expires_at, message_for_human), the status values, and when `api_key` appears. Nothing an agent needs to complete the request-and-poll flow 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 each of the four optional parameters is already documented, so the baseline is 3. The description adds that the human can lower or raise the requested limits and that supplying an email triggers the Approve email, but it does not add syntax or constraint 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?

The description states a specific verb and resource ('Get a live key') plus the concrete mechanism (human approves in one tap) and the endpoint. It also names the companion tool `check_access` for polling, so the agent can distinguish this from siblings without inspecting 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?

It gives clear conditions of use: call this when you need a live key approved by your human, then poll `check_access` every 5 seconds until approved. It even warns against a wrong approach ('Never ask your human to read you a code'). It does not, however, contrast against the sibling `get_sandbox_key`, which is the obvious alternative for non-live keys.

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 beyond the annotations by disclosing the quota model ('each job includes 2 revisions'), the failure semantics ('a failed revision doesn't use one'), and the key side effect that the returned text becomes the job's result — important for a non-idempotent mutation whose write is not declared destructive. It stops short of saying what error surfaces when both revisions are exhausted.

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 compact sentences, front-loaded with the action and purpose, each carrying real information (quota, failure behavior, return value). The trailing REST endpoint reference is marginal but brief and aids API cross-referencing.

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

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

With no output schema, the description usefully states the return value, and it covers the mutation's side effect and quota constraint for a non-idempotent write. Only the exhausted-quota error path and auth expectations (beyond the schema's api_key note) are left unaddressed.

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 job_id, note, and api_key are already documented, and the description adds no format or content guidance for the note. Baseline 3 is appropriate because the schema carries the full parameter burden.

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 ('Ask the agent to revise a completed job') and names the target state (completed job), which no sibling covers. An agent can distinguish it from get_job_result, rate_job, or open_dispute without opening a schema.

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

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

Implies the prerequisite that the job must be completed and explains the revision allowance, which guides when it is callable. However, it never contrasts with the nearest alternatives (rate_job, open_dispute, get_job_result) or states when to prefer dispute/re-rating instead of revising.

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: it discloses immediate and irreversible revocation, the exact failure mode for later calls (401 revoked_key), and that jobs/results survive and remain readable via other keys and /account. It also confirms sandbox and live keys are both affected, which the destructiveHint alone would not tell an agent.

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 action and its permanence, then layers consequences, data retention, scope, and the confirm requirement in short declarative clauses. Every sentence carries a distinct fact; nothing is redundant with the title beyond the necessary restatement of scope.

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 no output schema, the description supplies what an agent needs: irreversibility, downstream error behavior, data survival, key-type scope, and the confirm requirement. Nothing material is left 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 coverage is 100%, so the schema already documents both parameters; the description nonetheless reinforces the mandatory confirm gate for MCP callers, which is the one parameter behavior most likely to be gotten wrong. It adds nothing about the optional api_key parameter, so it does not fully earn a 5.

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 ('Revokes the API key') and narrows the scope precisely — the key making the call, not any key. The REST-equivalence note ('The same as DELETE /api/v1/key') removes any residual ambiguity and no sibling tool performs revocation, so the boundary 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?

Makes clear this operates only on the calling key, which is the critical precondition an agent needs, and states the invocation gate ('MCP tools need confirm: true'). No alternative tool is named, but none exists among the siblings, so there is little left to disambiguate.

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

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

Annotations already declare destructive and non-idempotent; the description goes beyond them by naming exactly what is destroyed ('the old secret stops signing at once') and that the value is returned only once, so it must be captured immediately. It does not cover rate limits or whether concurrent rotations invalidate each other, 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?

Four short sentences, front-loaded with the operation and followed by the critical consequence. The endpoint mapping sentence is slightly gratuitous for an agent but cheap and useful to some callers.

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 explains the return ('returns it once'), the invalidation semantics, and sandbox/live applicability — everything needed to call and handle the result. Missing only error/retry behavior if the caller loses the returned secret.

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 optional parameter, and the schema description already covers it fully at 100% coverage, including the key pattern and pointers to get_sandbox_key/request_access. The description adds no parameter-level detail, so the high-coverage 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 ('Makes a new webhook signing secret') and narrows scope to 'the API key making the call', which separates it from revoke_key and the set/get webhook-event siblings. The REST endpoint mapping reinforces the operation.

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

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

The operational timing ('update your verifier right away') is implied, but there is no explicit statement of when an agent should rotate versus use revoke_key, test_webhook, or set_job_webhook. Usage is inferable from the purpose 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?

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds useful context beyond that: it lists returned candidate fields including role, traits, starting price, and match rationale, and confirms the search is free with no key required. It does not explain pagination behavior for limit/offset.

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

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

The description is two sentences, front-loads the core action, and includes only useful details about returned data and access requirements. There is no 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 read-only search tool with no output schema, the description usefully states what is returned and that no key is needed. However, with seven optional parameters including aliases and pagination controls, it leaves significant gaps around filtering and pagination behavior.

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 71%, with limit and offset lacking descriptions. The description does not compensate by explaining query filters, department filtering, max price semantics, or pagination, so it adds little parameter 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?

The description states a specific verb and resource: "Find Roster agents for a task." It clearly identifies candidate discovery, but it does not explicitly distinguish this from siblings such as get_agent or hire_agent.

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 "for a task" implies the search use case, and "Free, no key needed" clarifies access requirements. However, it gives no explicit when-not conditions or alternatives such as using get_agent for full details or hire_agent to hire.

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 idempotent=true, destructive=false, so the safety bar is lower, but the description adds substantial context: null clears, a new URL requires the key's webhook secret (409 webhook_secret_missing), invalid hosts yield 400 bad_webhook_url, the key's event filter applies, redelivery uses the recorded URL, and the call is free. The only gap is what the successful response looks like.

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 lead sentence is well front-loaded, but the remainder is a dense run-on mixing endpoint paths, parenthetical asides, and status codes, with noticeable redundancy (the PUT /api/v1/webhooks/url path appears twice, and the closing 'The same as PUT /api/v1/webhooks/url' repeats the opening). It could be restructured into shorter, single-purpose statements without losing content.

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 with annotations but no output schema, the description covers prerequisites, validation, precedence, side effects, and cost — nearly everything needed to invoke it correctly. The one omission is the shape of the response after a successful set, which the description sidesteps by pointing at get_job_webhook.

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 real semantics beyond it: the precedence rule for which URL a job actually uses, the fact that clearing never requires the secret, and the https/public-host validation rule mirroring a job's webhook_url. The null-to-clear behavior is largely restated from the schema rather than extended.

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

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

Opens with a specific verb+resource and scope: 'Set a default webhook URL for your key's job events', including the exact event types covered. It then actively distinguishes itself from siblings by name (get_job_webhook, set_webhook_events, set_usage_alert), so an agent can route correctly without opening another 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 when-to-use rationale ('so you don't have to send webhook_url with every job'), names the read counterpart (get_job_webhook), the related filter tool, and an explicit exclusion ('doesn't change usage alerts'). It even states the resolution precedence, which tells the agent exactly when this tool's value takes effect versus a per-job override.

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

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

Goes well beyond the annotations: threshold-fires-once-per-key-per-America/New_York-day semantics, that a job refused with 429 never sends an event, signature scheme (Roster-Signature with the key's webhook secret) and retry behavior, sandbox key $0 events, and that the call returns the setting plus today's alerts. This is exactly the operational context annotations cannot carry.

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

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

Front-loaded with the action and effect, and nearly every sentence carries unique behavioral information. There is some redundancy — 'The same as PUT /api/v1/usage/alert' repeats the endpoint parenthetical from the opening line — and the single dense block is harder to scan than it needs to 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?

No output schema exists, and the description compensates by stating what is returned (the setting and today's alerts). With two fully documented optional parameters, an idempotent non-destructive mutation profile in the annotations, and explicit disable semantics, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so both webhook_url and api_key are already documented in the schema, including null-to-disable and the api_key header fallback. The description restates the null behavior but adds no new syntax or constraint meaning, 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 up front ('set an alert webhook on your key') and immediately scopes the effect: one signed usage.threshold event at 80% and 100% of the daily limit. It also names the read counterpart (GET /api/v1/usage) so the agent can distinguish mutating from reading tools in the sibling list.

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?

Frames the feature as optional and gives explicit operating instructions: 'Send {"webhook_url": null} to turn alerts off' and points at get_usage to inspect the current setting. It lacks an explicit statement of when to prefer set_webhook_events or test_webhook over this tool, so it stops short of full when/when-not guidance.

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

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

The description adds substantial behavior beyond the annotations: null means all events including future additions, [] disables all events, ping is always sent, filtered deliveries are recorded as skipped with skip_reason event_filtered, redelivery returns 409 until the event is re-added, and unknown event names return 400. These details clarify the mutation's semantics and side effects while remaining consistent with idempotentHint=true and destructiveHint=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?

The description is front-loaded with the main purpose, but it is a dense paragraph with redundancy: the PUT endpoint appears twice, the MCP tool name is restated, and 'or your human on /account' is irrelevant for an agent. Much of the content earns its place, but the same information could be structured more tightly.

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

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

Given the complexity of event filtering and the rich cross-references to related endpoints, the description is nearly complete: it covers defaults, disabling, future event inclusion, filtering behavior, redelivery conflicts, and unknown-name errors. It does not describe the response shape returned by this setter, and since there is no output schema, that is a remaining gap.

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

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

Schema coverage is 100%, so the schema already documents both parameters, but the description adds meaning beyond the schema for the events parameter: it explains null versus [] behavior, the default including later-added event types, and the 400 unknown_webhook_event error for invalid names. It adds no extra detail for api_key beyond what the schema provides.

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: choosing which webhook events the API key receives, with the exact event names listed. It also distinguishes the setter from the related GET tool that shows the current setting, so an agent can identify its function 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?

It gives clear context for when to use this tool: to set the key's event filter, with explicit pointer to get_webhook_events for viewing and test_webhook for ping validation. It does not explicitly distinguish this key-level filter from the sibling set_job_webhook 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?

Beyond the annotations (readOnlyHint=false, idempotentHint=false, openWorldHint=true), the description discloses the full behavioral profile: one attempt, no retries, 5 s timeout, signed with Roster-Signature and Roster-Event: ping, free, not counted as a job, excluded from the delivery list, and the two distinct 429 error codes with Retry-After. This is far richer than the annotations alone.

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?

Purpose is front-loaded and the dense detail is all relevant error/limit information. A few phrases ('without hiring anyone') add no value, and the single-wall-of-text format makes the fallback chain and error codes harder to scan than necessary, but nothing is truly 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 2-parameter tool with no output schema, the description covers everything an agent needs: target resolution, signature semantics, timeout/retry behavior, rate limits, distinct error codes, and side-effect profile (not a job, not in delivery list). Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real meaning beyond the schema: it states the multipart fallback resolution order (explicit webhook_url → key's job webhook URL → usage-alert webhook) and that the response's target field tells you which was used. That resolves the main ambiguity an agent would have about the optional 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?

The description opens with a specific verb and resource ('Send one signed ping event to check your webhook endpoint and signature verification') and closes by naming the exact REST equivalent (POST /api/v1/webhooks/test). This clearly separates it from siblings like redeliver_webhook, list_webhook_deliveries, and set_webhook_events.

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 explains exactly when to use it (verify endpoint reachability and signature verification before or alongside real traffic) and names the fallback chain when no URL is supplied. It also enumerates the when-not cases explicitly: 409 no_webhook_url, 409 webhook_secret_missing, and 429 rate/daily limits.

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