MyOTP.App

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

Beyond the read-only annotations, the description reveals plan-dependent behavior (DLR only on Enterprise plans), return field semantics (`is_active`, `expires_at`, `DLR`), and even decodes failure reasons like `failed.Undeliverable` and `failed.Provider`. This is rich behavioral context that annotations alone do not provide.

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, each earning its place: the first states the core function, the second details plan-dependent outputs with actionable failure semantics, and the third gives the use case and points to the correct alternative. The most important information is front-loaded, and there is no filler.

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

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

For a single-parameter, read-only tool with an output schema, the description fully covers what an agent needs: purpose, plan differences, failure meaning, and a clear distinction from the verification tool. The output schema handles return structure, so the description's omission of field types is appropriate.

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 thoroughly documents `message_id` as 'The UUID returned by `generate_otp` — this identifies which OTP you want a status report on.' The description adds no further parameter-specific 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?

The description opens with a specific verb and resource: 'Check whether a previously sent OTP is still active and ... get its delivery status.' It clearly differentiates itself from the sibling `verify_otp` by explicitly stating 'Does NOT verify a code; use `verify_otp` for that.' This leaves no ambiguity about the tool's role.

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 concrete use case: 'Useful when an end user reports they didn't receive the code — you can confirm whether MyOTP delivered it before deciding to resend.' It also names the alternative tool for code verification, providing both a when-to-use and when-not-to-use directive.

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 goes well beyond annotations by revealing the one-time API key return, the zero initial balance, and the timing difference between USDC and card top-ups. These details inform the agent about side effects and post-creation behavior that annotations do not specify.

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 with no redundant wording. It front-loads the core purpose and then provides essential behavioral notes, making every sentence earn 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 an output schema available, the description need not explain return values. It covers the essential operational context: creating an account, API key requirement, starting balance, and top-up activation conditions. Nothing critical seems missing for an agent to invoke 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 description coverage is 100%, so the schema already documents both parameters. The description does not add parameter-specific meaning beyond the schema, which matches the baseline for high schema coverage.

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

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

The description clearly states the specific action: create a MyOTP.App agent account and return its one-time API key. It distinguishes this tool from sibling tools by the verb 'create' and the resource 'account', which no other sibling covers.

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 notes that no API key is required for this tool, which is a clear usage condition. The description also provides context about what to expect after creation (zero balance, top-up behavior). However, it does not explicitly mention alternatives or when not to use the tool, though the distinction is obvious from sibling 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 are only coarse hints (readOnlyHint=false, idempotentHint=false), so the description carries the behavioral burden — and it delivers: it discloses that no new OTP is sent, that the mutation adds `duration` to `expires_at`, that the EXTEND_OTP entitlement (Business or Enterprise) is required, and that some destination countries cause a 403. No contradiction with annotations; readOnlyHint=false aligns with the mutating behavior described.

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?

Six sentences, each earning its place: purpose, use case, mutation semantics, entitlement requirement, failure mode, and alternative comparison. The core purpose is front-loaded in the first sentence and there is no fluff or needless repetition of schema 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 simple 2-parameter tool with an output schema and 100% parameter coverage, the description covers everything needed for correct selection and invocation: purpose, when to use, exact mutation behavior, auth requirement, and a specific error mode. Minor gaps remain — behavior when the OTP is already expired and whether extensions can be stacked — but these do not block correct use.

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%: both message_id (UUID from generate_otp, identifies the OTP) and duration (range, semantics of addition) are already fully documented in the schema. The description's 'Adds duration seconds (60-14400) to the current expires_at' reinforces but does not add new parameter information, so the baseline 3 for high schema 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+resource: 'Extend the expiry time of an active OTP', with the key qualifier 'without sending a new one'. The closing line explicitly differentiates it from the sibling generate_otp ('Cheaper and less spammy than calling generate_otp again'), and the purpose is distinct from verify_otp and check_otp_status. An agent can tell what this tool does and what it is not.

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 when-to-use scenarios: 'end user is taking longer than expected to enter the code (e.g., switched apps, dealing with carrier delivery delay)'. Names the main alternative explicitly ('generate_otp') with a comparative reason to prefer this tool. It lacks explicit when-not-to-use exclusions, but the 'active OTP' precondition and the 403 country caveat imply the boundaries.

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 indicate this is a non-read-only, non-idempotent action, and the description explicitly notes that each call deducts credits and returns the cost. It also mentions the 409 conflict on duplicate sends and the behavioral impact of force_send. This adds significant value beyond the 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?

The description is reasonably concise but carries a lot of key information in the first few sentences. It front-loads the purpose and return value, then gives usage guidance. It is not overlong given the complexity, but could be slightly trimmed without losing 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?

Given the tool's complexity (9 parameters, output schema, entitlements), the description covers the core actions, return value, and high-level constraints. It doesn't enumerate every entitlement or channel nuance, but the schema and output schema provide that detail. Some gaps remain (e.g., exact cost calculation), but overall it's complete enough.

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 descriptions are thorough, but the overall description adds meaning by explaining how parameters interact, e.g., otp_length requiring an entitlement, template_order overriding otp_validity on WhatsApp. This helps the agent understand the constraints beyond basic schema types.

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 clearly states the tool sends a one-time password via multiple channels and identifies the core use cases (signup, 2FA, password reset). It differentiates from siblings by mentioning the returned message_id used by related tools. The verb 'send' and resource 'OTP' are explicit.

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

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

The description explicitly states when to use the tool ('whenever an app needs to verify someone's phone') and provides context for when not to use it (e.g., avoiding repeated sends that trigger spam filters). It also references sibling tools (verify_otp, check_otp_status, extend_otp) for follow-up actions.

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 the safety profile is covered. The description adds useful behavioral context beyond annotations by noting that the response always includes email and may include balance/credit/plan info depending on plan and platform version, plus the connection-check implication of a successful 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?

The description is three sentences with no filler. The core purpose is front-loaded, followed by return variability and a practical use-case sentence; each sentence contributes meaningful guidance.

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

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

For a zero-parameter, read-only tool with an output schema and strong annotations, the description is complete. It covers what the call does, what the response minimally contains, and how to interpret success, so an agent has enough to select and invoke 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?

The tool has zero parameters, so there is no parameter burden for the description to carry. The baseline of 4 applies, and the description appropriately focuses on return behavior rather than parameter syntax.

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: returning account details for the API key in use. It is clear in scope, though it does not explicitly differentiate itself from the sibling get_account_status, so the purpose is clear but sibling distinction is left 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 description gives an explicit usage context: use as a sanity check when wiring up MyOTP for the first time, with a concrete success criterion (API key and IP whitelist are configured). It does not name alternatives or exclusion conditions, but the provided guidance is actionable and specific enough.

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 discloses that resend_verification triggers another confirmation email, which is a meaningful side effect consistent with readOnlyHint=false. It also adds account-state context (USDC top-up possible, cards stay locked) that goes beyond the annotations. No contradiction with annotations found.

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 carry all essential information: the first defines the tool's output, the second explains the optional flag and adds a relevant account-state constraint. No redundant wording or 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 the tool has only one optional parameter, a rich output schema, and no nested objects, the description covers the main purpose, the side-effect behavior, and a useful account-state nuance. It lacks explicit sibling differentiation, but overall the context is sufficiently complete for an agent to invoke 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%, and the schema already documents resend_verification as 'Send another confirmation email before returning account status.' The description repeats this idea in prose without adding new parameter semantics, 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 ('Return') and resource ('email verification, balance, plan, and status for the configured MyOTP agent account'), so the purpose is clear and concrete. However, it does not explicitly differentiate this from the sibling get_account_info, which may overlap in scope.

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

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

The description implies when to use the tool by stating what it returns and includes the conditional resend_verification behavior, plus a note about unverified accounts topping up. It does not explicitly name alternatives or state when not to use this tool, so usage guidance is present but not strong.

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, openWorldHint, and destructiveHint=false. The description adds meaningful behavioral context beyond those: it performs no purchase, returns live pricing and payment options, and 'never exposes the configured API key' — a critical safety guarantee for the agent. No contradiction with 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?

Three tightly written sentences, each earning its place: what it does, when to use it, and what it returns. The most important scoping statement ('without making a purchase') is front-loaded, and there is zero redundant 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 one-parameter, read-only quote tool with a full output schema, the description is complete. It covers purpose, triggers, safety, and return characteristics. The output schema handles return-value details, so nothing critical is missing for an agent to invoke 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?

The input schema has 100% description coverage for the sole 'credits' parameter, including type, range, default, and meaning, so the schema already carries the full burden. The description adds no additional parameter-specific guidance, so the baseline of 3 is appropriate.

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

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

The description has a specific verb ('Get'), a specific resource ('live price and payment options for buying MyOTP credits'), and explicitly distinguishes itself from purchase actions: 'without making a purchase.' It also names its sibling relationship by referencing top_up_credits and generate_otp failures, leaving no ambiguity about what this tool does.

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 concrete trigger conditions: use it when generate_otp or another send fails with HTTP 403 insufficient balance / NoBalance, or before calling top_up_credits to show the cost. This is explicit, actionable guidance that tells an agent exactly when to select this tool over alternatives.

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 it read-only, idempotent, and non-destructive; the description adds meaningful behavioral constraints: max 31-day range, default page/per_page/date window, and the API_REPORTING entitlement requirement. This gives the agent a clear picture of side-effect-free paginated retrieval.

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 sentences, each serving a purpose: purpose, payload fields, constraints/defaults, and use cases. The most decision-relevant information (what it fetches) is front-loaded, and there is 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 the 4 optional parameters, full schema coverage, read-only annotations, and output schema presence, the description is sufficient for an agent to invoke correctly. It covers entitlement, defaults, constraints, and intended use without redundancy.

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 input schema already fully documents each parameter, including defaults and the 31-day limit. The description repeats those defaults rather than adding new parameter-level semantics, 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 opens with a specific verb and resource: 'Fetch a paginated list of OTP transactions for a date range.' It enumerates returned fields and states the scope, distinguishing it from sibling OTP lifecycle tools like generate_otp or verify_otp.

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 lists intended use cases: audit recent activity, build internal dashboards, reconcile billing, or debug delivery issues across many recipients. It does not name alternative tools directly, but the sibling list and the use-case framing make the reporting-versus-operational distinction 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?

Beyond the annotations, the description clearly explains the two-mode behavior: quote-first with a 402 challenge plus retry details, or direct credited response when an MPP runtime wraps the fetch. The destructiveHint=true annotation is surprising for a top-up, but the description's mention of completing a purchase is consistent with side-effecting financial behavior, not a contradiction.

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-loaded with the purpose and trigger condition. Every sentence contributes essential behavioral or routing information, with no repetition or filler.

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

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

For a financial side-effecting tool with output schema, annotations, and full parameter documentation, the description covers the trigger, workflow, and conditional behavior sufficiently. Nothing critical is missing for an agent to decide whether and how to invoke it.

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 parameter details are already fully documented. The description does not add additional meaning about credits or dry_run beyond what the schema provides, making the baseline score of 3 appropriate.

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

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

The description states a clear verb and resource: prepare or complete a MyOTP credit purchase using USDC/card through MPP. It also differentiates itself from siblings by describing both the quoting and payment-completion workflow, making it distinct from get_topup_quote.

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 a concrete trigger: use when generate_otp or another send fails with HTTP 403 insufficient balance / NoBalance. It does not explicitly name alternatives or state when not to use this tool, but the triggering condition is clear and actionable.

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 clearly discloses that a successful verification consumes the OTP so it cannot be reused, and that expired codes fail. It also enumerates the exact failure reasons ('invalid' | 'expired' | 'not found'), adding meaningful behavioral detail beyond the readOnlyHint=false annotation.

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?

Every sentence adds necessary information: what it does, success/failure behavior, consumption side effect, required identifier selection, and when to call. It is compact but complete, well-structured, and free of 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 the output schema and the strong input schema, the description covers the essential operational context: the verification flow, required identifier, expiring/consumption behavior, and expected return statuses. An agent has enough information to call this tool correctly without ambiguity.

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 already provides 100% coverage with detailed descriptions for each parameter. The description adds crucial usage semantics not fully captured by the schema: you must pass either phone_number or message_id, and message_id is preferred because it disambiguates multiple OTPs for the same number.

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?

Description states a specific verb ('Verify'), the exact resource ('the OTP MyOTP delivered'), and the intended context (end-user code submission). The stated outcomes—success or failure with reasons—clearly differentiate it from a plain status check like check_otp_status.

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 says when to call: 'Call this after collecting the code from the user (login form, signup screen, etc.)'. It also clarifies the required identifying parameter, prefers message_id over phone_number, and explains why. It does not name alternative tools or explicitly say when not to use them, but the context is clear.

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