Instamojo MCP by usefulapi

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true; the description adds real value on top by clarifying that no money moves at creation time, that buyer contact only happens when send_email/send_sms are true, and that the endpoint is POST /payment-requests/. It omits auth requirements and rate limits.

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 tight sentences, front-loaded with the "WRITE:" marker and the primary outcome, then money semantics, then notification caveats, then the endpoint. No filler sentences.

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 10 parameters and no output schema, the description compensates by naming the return fields (id, longurl, shorturl) and the unit of amount. Only the broader response payload shape and error behavior are left unmentioned, which is acceptable.

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 every parameter (including the email/phone-conditional and webhook/redirect semantics) is already documented in the schema. The description's notes on INR and the email/phone prerequisites largely restate schema content, so it sits at the baseline rather than adding new meaning.

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 ("create a payment request (a payment link)") plus the returned artifacts (id, longurl, shorturl), which cleanly separates it from siblings like instamojo_get_payment_request, instamojo_list_payment_requests and the enable/disable pair.

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?

Explains the transactional model — nothing is charged and the buyer pays on the link — plus the conditional notification behavior, which tells the agent when this tool versus a charge/refund flow applies. It does not explicitly name a sibling to prefer or state exclusions, so it stops short of full routing 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?

Goes well beyond destructiveHint=true by disclosing the irreversible business rule (only ONE refund per payment, partial refunds cannot be topped up) and the dry-run/confirm gating behavior. This is exactly the context an agent needs before moving money.

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 warning and confirm workflow are front-loaded, which is good. But the full reason-code glossary duplicates the schema's enum descriptions word-for-word, consuming a large share of the text for zero added information.

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

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

For a destructive, no-output-schema money-movement tool, it covers the safety essentials: preview behavior, irreversibility, and the partial-refund constraint. Minor gaps remain (transaction_id replay protection and error/duplicate-call behavior are only in the 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 baseline is 3; the description earns more by explaining how confirm changes the call's effect and by tying refund_amount semantics to the one-refund-only constraint. It loses a point for restating the enum reason codes verbatim rather than adding meaning.

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 an explicit verb+resource ('refund a payment, in full or in part') and a WRITE/moves-money label. The scope (one refund per payment) and endpoint are stated, which clearly separates it from read-only siblings like instamojo_get_refund and instamojo_list_refunds.

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 a concrete usage protocol: call without confirm to get a preview, ask the user, then call again with confirm: true. It does not name sibling alternatives (e.g. use instamojo_get_refund to check status), so it falls just 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 destructiveHint=true and openWorldHint=true; the description adds value beyond that by stating what is NOT affected (existing payments are untouched) and that the state is reversible via enable. It also surfaces the underlying endpoint, but does not mention idempotency of repeated disables or error behavior for an already-disabled request.

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 a 'WRITE:' marker, then effect, reversibility, side-effect scope, and endpoint in roughly two sentences. No filler and nothing an agent needs is 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?

For a single-parameter state-change tool with no output schema, the description covers the mutation's effect, its reversibility, and the blast radius (existing payments unaffected). Combined with annotations that flag it as destructive, an agent has everything needed to call it 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?

Only one parameter and schema description coverage is 100%, so the pattern and required-ness are fully documented by the schema. The description adds no extra meaning about the id format or where to obtain it, 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 (disable) plus resource (payment request) and the concrete effect: the link no longer accepts payments. It explicitly distinguishes itself from instamojo_enable_payment_request, so an agent can separate the pair 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?

Clear usage context: use it to stop a payment link from accepting payments, and the reverse operation is named. There is no explicit 'when not to use' guidance (e.g. versus deleting or letting it expire), but the selection signal against the sibling is unambiguous.

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 carry openWorldHint and idempotentHint, so the description usefully supplies the mutation semantics ('WRITE:') and the real-world effect on the payment link. It does not say what happens if the request is already enabled (error vs. no-op), which is the one behavior an agent would still want confirmed.

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

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

One front-loaded sentence beginning with the mutation marker and the verb, followed by the endpoint. No filler whatsoever.

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 mutation with annotations covering idempotency and open-world scope, the description covers purpose and effect adequately. The missing piece is the already-enabled case, which matters given idempotentHint=true.

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 coverage is 100%, so the schema already documents payment_request_id fully. The description adds no format or lookup guidance beyond that, 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 ('enable a previously disabled payment request') plus the concrete outcome ('its link accepts payments again'), and the WRITE prefix plus endpoint make it trivially distinguishable from the disable sibling.

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

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

The precondition 'previously disabled' implicitly tells the agent when this applies, and the sibling set makes the alternative (instamojo_disable_payment_request) obvious. It never names the alternative or states when not to use it explicitly, so it stops short of 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=true, but the description adds valuable behavioral context: it enumerates returned fields and clarifies status semantics such as Credit = paid and Failed. It does not discuss error cases or not-found behavior, which keeps it below 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?

The definition is one compact sentence with the core operation front-loaded and no wasted language. Its density is appropriate because every clause carries return-field or status information.

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

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

With no output schema, the description appropriately compensates by listing the fields returned and explaining status values. It is largely complete for a single-record read, though it omits edge cases such as invalid or missing ids.

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 single payment_id parameter is already documented with pattern and example. The description reinforces the MOJO-prefixed id format but adds no syntax or sourcing detail 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 resource and scope: one payment retrieved by its id. It effectively distinguishes payments from sibling payment-request/refund tools through the resource, though it does not explicitly name an alternative 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?

Usage is implied: call this with a payment id to retrieve a single payment. There is no explicit when-to-use/when-not guidance or comparison to sibling tools such as instamojo_get_payment_request.

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=true, so safety profile is covered. The description adds genuine value beyond that by disclosing the response composition (status plus payments made against it) despite there being no output schema, though it says nothing about missing-id/404 behavior.

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

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

A single sentence that front-loads the tool's purpose, appends the return payload, then the sibling routing hint and the underlying endpoint. Every clause carries information; nothing is padding.

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

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

For a one-parameter read tool with no output schema, the definition covers what it fetches and roughly what comes back, which is enough to call it correctly. It stops short of detailing the full field set of a payment request or error conditions, so not 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?

Schema coverage is 100% and the schema itself explains the 32-character hex id and its origin in instamojo_list_payment_requests. The description only restates 'by id' and adds no format or source detail beyond 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?

States a specific verb and resource ('one payment request by id') plus the payload content ('status and the payments made against it'). The singular 'by id' scope implicitly but clearly separates it from instamojo_list_payment_requests, and it even names the sibling that consumes the returned payment ids.

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

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

Usage is implied by the 'by id' scope, and the description routes downstream work to instamojo_get_payment. However, it never explicitly says when to call this instead of instamojo_list_payment_requests, nor what to do if the request id is unknown.

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=true, so the safety profile is covered. The description adds the underlying endpoint shape (GET /refunds/{id}/), which is mildly useful context, but says nothing about what is returned or failure behavior for an invalid id.

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?

Very short and front-loaded — the core purpose leads, with provenance and endpoint as trailing fragments. Nothing is wasted, though the trailing HTTP path is of marginal use to an agent.

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?

A simple single-parameter read with full schema coverage and annotations carrying the safety profile; the description covers what it does and where the id comes from. The only gap is that no output shape is described, and there is no output schema to compensate.

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 the single parameter; the description still adds value by giving a concrete id example (C5c0751272) and its provenance ('case id from instamojo_list_refunds'), clarifying the expected format beyond the pattern regex.

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 ('One refund by its id') and disambiguates against the sibling list tool by naming instamojo_list_refunds as the source of the id. It could be sharper about it being a single-record fetch versus the list, but an agent can tell the two apart.

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?

Provides a clear precondition: the id is the 'case id from instamojo_list_refunds'. That effectively routes the agent to the right sibling first. No explicit when-not or error handling is given, so it falls 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=true, so the safety profile is covered; the description adds real value on top by naming the status values (Pending, Sent, Failed, Completed) an agent will encounter and disclosing the pagination mechanism. It stops short of describing default page size handling or the shape of the paging envelope.

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

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

One compact sentence listing the payload, then a pagination hint and the endpoint. Front-loaded with the action and resource, no filler, every clause carries information.

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

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

With no output schema, the description compensates by enumerating the fields returned (id, purpose, amount, buyer, status, URLs, timestamps), which is what an agent needs to plan downstream steps. The only gap is not stating the pagination envelope or how to detect the last page.

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 both parameters already document their ranges, defaults and the next_page pattern. The description's 'use next_page' line largely repeats the schema, so the baseline 3 applies — no additional semantics such as what limit to choose or how deep paging behaves.

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 ('List the payment requests (payment links) of the account') and enumerates the returned fields, which is well beyond restating the name. The plural 'List' implicitly separates it from instamojo_get_payment_request, but no sibling is named explicitly.

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

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

The pagination instruction ('Paged: use next_page') gives concrete usage guidance for multi-page retrieval. However, there is no statement of when to prefer this over instamojo_get_payment_request for a single record, nor any prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context beyond that: the underlying GET /refunds/ endpoint and the fact that results are paged via next_page. It omits auth/rate-limit details, which is a minor gap given the annotation coverage.

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, front-loaded with the core purpose and followed by pagination guidance and the endpoint. The field enumeration is slightly dense but every element (returned fields, paging, endpoint) is functional.

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

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

For a simple read-only listing tool with annotations covering safety and a fully described schema, the definition is complete. The absence of an output schema is offset by the description naming the fields returned. Only marginal gaps (no auth/pagination mechanics detail) remain.

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 page and limit are already documented in the schema, including the next_page hint. The description's 'Paged: use next_page' echoes the schema rather than adding new meaning, 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 (List) and resource (refunds), and enumerates the fields returned (id, payment id, status, reason type, amounts, date). It does not explicitly name or differentiate from the singular sibling instamojo_get_refund, but the 'list' framing and field enumeration make the purpose 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?

The description implies usage (browse/paginate refunds) and notes 'Paged: use next_page', but gives no explicit when-to-use versus when-not guidance, and never contrasts with instamojo_get_refund for single-record retrieval. The context is inferable but not spelled out.

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