NOTIFY

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

Annotations only say it is non-read-only, non-idempotent and non-destructive. The description adds substantial behavior the annotations cannot carry: the five-attempt budget that closes a verification, the fact a wrong code costs an attempt, and a full error taxonomy with meanings (recipient_mismatch, verification_closed, verification_expired, etc.).

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, then outcome semantics, then the error list — a sensible order. It is slightly redundant, stating the 'approved only, everything else is not approved' rule twice in adjacent sentences, but nothing is 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?

There is no output schema, so the description must carry return semantics, and it does: the success signal (200/approved) and every error code with its meaning and required follow-up. An agent has everything needed to call it 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 description coverage is 100%, so all four parameters are already documented, including the api_key convention and the `to` pattern. The description adds flow context around `to` (it must match the number the code was sent to, else recipient_mismatch) but no format or syntax 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 states a specific verb and resource — checking the code the human typed against the number it was sent to — and frames the outcome (verification only on approval). An agent can distinguish this from start_verification, which creates verifications rather than checking 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?

It gives explicit decision rules: only admit the user on a 200/approved result, treat every other answer, timeout and network error as not approved, never self-retry, and ask the human for a new code. The `too_many_attempts` branch even points to starting a new verification as the alternative path.

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 readOnlyHint=false and destructiveHint=false; the description adds substantial behavioral context: the key never sends a real SMS or spends credits, the claim_url transfers ownership to whoever confirms, and there are per-minute and per-day rate limits per address. It also flags the secret-handling risk (never in source, logs, or tickets).

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 core action is front-loaded in the first sentence and each subsequent sentence carries distinct weight (security, ownership, live-key alternative, rate limits). It runs long and could be tightened, but there is little pure filler.

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

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

With no output schema, the description compensates by explaining the returned fields (api_key and claim_url) and how to use them. Combined with secret-handling and rate-limit guidance, an agent has everything needed to call it and handle the result safely.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description instead documents how the returned value should be consumed, which is useful but not a parameter-semantics contribution.

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 an sk_test_ API key instantly,' and immediately names the concrete artifact returned (sk_test_ key, claim_url). The resource (a test API key) is unmistakably distinct from the sibling tools get_message and send_message, which consume the key rather than produce it.

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

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

It gives explicit when-to-use (build and verify an integration without spending credits) and when-not-to-use (real SMS need an sk_live_ key created on the dashboard), plus the alternative of reusing an existing key. It also states exactly where the key goes (api_key to send_message/get_message, config not source) and who may use the claim_url.

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 safety profile (readOnly, idempotent, non-destructive, closed-world), but the description adds substantial behavior the annotations cannot convey: it is a polling loop, which states are final, backoff cadence, and a hard time limit with a do-not-resend rule. That is exactly the extra context an agent needs to avoid hammering the endpoint or double-sending.

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 purpose, then the polling protocol in three tightly packed sentences. No filler; the timing numbers and terminal-state list are the operative content and every clause is actionable.

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 it does so by enumerating the status lifecycle the caller will observe. Combined with the timeout and backoff guidance, an agent has everything needed to invoke and interpret this 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 coverage is 100%, so the baseline is 3; the description goes beyond it by adding a cross-parameter constraint the schema does not state — the key must belong to the same project as the message being read. That reframes api_key as scoping rather than mere auth, which is a genuine, if modest, addition.

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 ('Read') and resource ('current state of a message'), and anchors the resource to 'a message sent with a key of the same project', which ties it directly to the send_message sibling. An agent can immediately tell this is the read/poll counterpart to send_message, not a send or key-creation 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?

Exceptionally explicit: it says to poll only while status is queued or submitted, names the terminal states (delivered, undeliverable, failed) and the never-changing state (unknown), prescribes backoff (start ~2s, double, cap at 30s), and gives a timeout policy with the correct fallback action (treat as unconfirmed, do not resend). This is a complete when/when-not/how-often protocol.

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 far beyond the annotations: test-key simulator behavior per recipient number, that a live send spends one credit per segment, that 'submitted' is not yet delivery, that 'unknown' must not be retried automatically, and that 'replayed: true' means no second SMS. This is exactly the operational context an agent needs before firing a side-effecting call.

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

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

Well front-loaded: purpose, then access rules, then test behavior, then result interpretation. It is long and duplicates the template/placeholder list already present in the schema, which costs a point, but every paragraph carries operational value.

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 complex, side-effecting tool with no output schema, the description covers recipient restrictions, template semantics, idempotency behavior, and how to read message.status and message.error. An agent could call it correctly, including failure handling, from this text alone.

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 mostly restates what the template and idempotency_key schema entries already say (template list, no free text, reuse keys only for identical retries), though it adds the cross-field constraint that a team template combined with an unconfirmed recipient returns recipient_not_on_team.

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 opening sentence states a specific verb, resource, channel and geographic scope: 'Send one transactional SMS to a Georgian mobile number.' It also clarifies the hard constraint that text is never free-form. It does not differentiate itself from the sibling start_verification, which plausibly also triggers an SMS, so an agent must infer the boundary.

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

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

Explicitly gives when-to-use conditions (team templates only to dashboard-confirmed numbers, test numbers with a test key), when-not (live key requires service/job names from the owner's list), and error routing ('ask the human to add it on the dashboard, and never retry by yourself'). It also routes to the sibling get_message for the final outcome, so nothing is left to inference.

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

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

Annotations cover the safety/idempotency profile (readOnlyHint=false, idempotentHint=true, openWorldHint=true), and the description still adds substantial context beyond them: 10-minute/5-check code lifetime, one-time use, replacement semantics, test-key simulation behavior per test number, credit spend on live keys, `replayed: true` meaning, and the provider_unavailable retry rule with the same idempotency_key.

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 and the check_verification handoff are front-loaded, and the test-key paragraph is a compact enumeration of edge cases. It is long and repeats the test-number range already present in the schema, but for a tool with this many failure modes most sentences earn their 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: it explains `replayed: true`, the `failed` status for a refused SMS, `provider_unavailable` as an error with retry guidance, `pending` as inconclusive, and `too_many_verifications` with `retry_at`. Rate limits (5 starts/minute, 5/hour, 10/24h) and auth requirements for live vs test keys are all covered.

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: how idempotency_key interacts with `replayed: true`, that a new start replaces the previous code for the same number, and that the template determines the message that carries the code and the named 10-minute window. These are genuine semantic additions rather than restatement.

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 ('Verify a Georgian mobile number') and immediately explains the mechanism: a random six-digit code sent by SMS via a built-in template. It also routes the agent to the natural sibling ('ask the human for the code they received, then call check_verification'), so the agent can distinguish this from check_verification 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?

Gives explicit when-to-use and when-not guidance: use check_verification after obtaining the human's code, use test numbers rather than one number for repeated test starts, and on too_many_verifications tell the human the retry_at time and 'never retry by yourself'. Alternatives and exclusions are both named.

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