Exposes Conekta's core payment operations as tools, enabling management of customers, orders, charges, refunds, subscriptions, and checkouts via the Conekta payment API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Conekta MCP Server show my current account balance"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for the Conekta payment API. Exposes Conekta's core payment operations as tools for the Model Context Protocol.
# Install dependencies
uv sync
# Set your Conekta API key
export CONEKTA_API_KEY=key_your_api_key
# Run the server
uv run python -m conekta_mcpBy default the server uses the stdio transport for local MCP clients such as Claude Desktop.
Related MCP server: Vaultix MCP Server
The server is available remotely over Streamable HTTP at:
https://mcp.conekta.com/mcpUse this endpoint if you want to connect to the hosted Conekta MCP server. Send your Conekta API key in the request header:
Authorization: Bearer key_xxxIf your MCP client supports remote servers over HTTP, the JSON config should include the hosted URL and the Authorization header.
Example:
{
"mcpServers": {
"conekta": {
"url": "https://mcp.conekta.com/mcp",
"headers": {
"Authorization": "Bearer key_xxx"
}
}
}
}Notes:
Replace key_xxx with your real Conekta private API key.
The header must be exactly Authorization.
The value must include the Bearer prefix.
claude mcp add --transport http conekta https://mcp.conekta.com/mcp \
--header "Authorization: Bearer key_xxx"Replace key_xxx with your real Conekta private API key.
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"conekta": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/mcp", "run", "python", "-m", "conekta_mcp"],
"env": {
"CONEKTA_API_KEY": "key_your_api_key"
}
}
}
}Resource | Tools |
Balance |
|
Customers |
|
Orders |
|
Charges |
|
Refunds |
|
Plans |
|
Subscriptions |
|
Checkouts |
|
Events |
|
Companies |
|
docker run --pull=always -i --rm \
-e CONEKTA_API_KEY=key_your_api_key \
ghcr.io/conekta/mcp-server:latest{
"mcpServers": {
"conekta": {
"command": "docker",
"args": ["run", "--pull=always", "-i", "--rm", "-e", "CONEKTA_API_KEY", "ghcr.io/conekta/mcp-server:latest"],
"env": {
"CONEKTA_API_KEY": "key_your_api_key"
}
}
}
}# Install with dev dependencies
uv sync --extra dev
# Run tests
uv run pytest tests/ -vCancel a payment link (checkout).
Args: checkout_id: The Conekta checkout ID to cancel
| Name | Required | Description | Default |
|---|---|---|---|
| checkout_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the action ('Cancel') but lacks details on permissions needed, whether cancellation is reversible, effects on related resources, or error conditions. This is a significant gap for a mutation tool.
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 core purpose in the first sentence, followed by parameter details. It's efficient with minimal waste, though the parameter explanation could be integrated more smoothly.
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 an output schema (which handles return values), no annotations, and low schema coverage, the description is moderately complete. It covers the basic action and parameter meaning but lacks behavioral context and usage guidelines, making it adequate but with clear gaps.
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 0%, so the description must compensate. It adds the meaning of 'checkout_id' as 'The Conekta checkout ID to cancel', which clarifies the parameter's purpose. However, it doesn't provide format examples or constraints, leaving some ambiguity.
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 verb ('Cancel') and resource ('a payment link (checkout)'), making the purpose immediately understandable. It distinguishes from siblings like 'cancel_order' or 'cancel_subscription' by specifying it's for checkouts, though it doesn't explicitly contrast with 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?
No guidance is provided on when to use this tool versus alternatives like 'cancel_order' or 'cancel_subscription', nor are prerequisites or context for cancellation mentioned. The description only states what it does, not when it should be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel an order.
Args: order_id: The Conekta order ID to cancel
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'Cancel an order' but doesn't explain what cancellation entails—whether it's reversible, requires specific permissions, triggers refunds, affects inventory, or has rate limits. For a mutation tool with zero annotation coverage, this leaves critical behavioral traits unspecified.
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 brief and front-loaded with the core purpose ('Cancel an order.'), followed by parameter details. There's no wasted text, and the structure is clear. However, the Args section formatting is slightly verbose for a single parameter, keeping it from a perfect score.
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 this is a mutation tool with no annotations, 1 parameter, and an output schema (which handles return values), the description is minimally adequate. It covers the purpose and parameter semantics but lacks behavioral details (e.g., side effects, error conditions) and usage guidelines, leaving gaps for an agent to use it correctly in context.
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 description adds meaningful context for the single parameter: 'order_id: The Conekta order ID to cancel'. This clarifies that 'order_id' refers to a Conekta-specific identifier, which is valuable since schema coverage is 0% and the schema only provides a generic title 'Order Id'. The description compensates well for the low 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 action ('Cancel') and resource ('an order'), making the purpose immediately understandable. It distinguishes from siblings like 'cancel_checkout' and 'cancel_subscription' by specifying the order resource. However, it doesn't specify what 'cancel' entails operationally (e.g., refund, status change).
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?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., order must be in a cancellable state), exclusions (e.g., cannot cancel after shipping), or comparisons to siblings like 'update_order' for status changes. The description only states what it does, not when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel a subscription.
Args: customer_id: The Conekta customer ID subscription_id: The subscription ID to cancel
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | Yes | ||
| subscription_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the action is 'cancel' but doesn't clarify if this is reversible, requires specific permissions, triggers notifications, affects billing, or has rate limits. For a destructive operation with zero annotation coverage, this leaves critical behavioral traits undocumented.
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 appropriately concise with a clear title phrase followed by parameter listings. Every sentence serves a purpose: the first states the action, and the Args section documents parameters. However, the structure could be more front-loaded by integrating parameter context into the main description rather than a separate section.
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 this is a destructive operation with no annotations, 0% schema coverage, but an output schema exists, the description is minimally adequate. The output schema likely covers return values, reducing the need for that in the description. However, for a subscription cancellation tool, it should address behavioral aspects like permanence, billing implications, and error conditions more thoroughly.
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 0%, so the schema provides no parameter documentation. The description adds basic semantics by identifying parameters as 'customer_id' and 'subscription_id', but doesn't explain format (e.g., UUID), sourcing (where to find these IDs), or validation rules. It partially compensates for the schema gap but leaves important details unspecified.
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 action ('Cancel') and resource ('a subscription'), making the purpose immediately understandable. It distinguishes this from siblings like 'pause_subscription' and 'resume_subscription' by specifying termination rather than temporary suspension. However, it doesn't explicitly contrast with 'cancel_order' or 'cancel_checkout', leaving some sibling differentiation incomplete.
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 provides no guidance on when to use this tool versus alternatives like 'pause_subscription' or 'cancel_order'. It doesn't mention prerequisites (e.g., subscription must be active), consequences (e.g., immediate termination vs. end of billing period), or recovery options. The agent must infer usage from context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture a pre-authorized order payment.
Args: order_id: The Conekta order ID to capture
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool captures a payment, implying a financial transaction, but doesn't disclose critical details like authentication requirements, rate limits, side effects (e.g., whether this finalizes the order), or error conditions. This is inadequate for a payment-related tool with zero 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?
The description is extremely concise and front-loaded, with the core purpose in the first sentence and parameter details in a clear 'Args' section. Every sentence earns its place without redundancy, making it easy to parse quickly.
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 (payment capture with financial implications), lack of annotations, and presence of an output schema, the description is minimally adequate. It covers the basic purpose and parameter semantics but lacks behavioral details and usage guidelines, which are important for safe operation. The output schema mitigates some gaps by documenting return values.
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 description adds meaningful context for the single parameter by specifying it's a 'Conekta order ID', which clarifies the expected format beyond the schema's generic 'string' type. With 0% schema description coverage and only one parameter, this compensates well, though it could benefit from examples or constraints (e.g., ID format).
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 action ('capture') and resource ('pre-authorized order payment'), making the purpose understandable. However, it doesn't explicitly differentiate from siblings like 'create_order' or 'update_order' which also involve order operations, leaving some ambiguity about when this specific capture action is needed versus other order-related tools.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., that the order must be pre-authorized), exclusions, or comparisons to sibling tools like 'cancel_order' or 'update_order', leaving the agent to infer usage context from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a payment link (checkout).
Args: name: Checkout name for identification recurrent: false for single use, true for multiple payments expires_at: Expiration Unix timestamp (10 minutes to 365 days from now) allowed_payment_methods: Comma-separated payment methods (e.g., "card,cash,bank_transfer") order_template_currency: ISO currency code (e.g., MXN) item_name: Product name for the line item item_unit_price: Price per unit in cents (e.g., 50000 for $500.00 MXN) item_quantity: Number of units (default 1) needs_shipping_contact: Whether shipping contact info is required (default false) customer_info_customer_id: Existing Conekta customer ID (e.g., cus_2tXyF9BwPG14UMkAA) customer_info_name: Customer name (if not using existing customer) customer_info_email: Customer email (if not using existing customer) customer_info_phone: Customer phone E.164 (if not using existing customer) line_items_json: JSON array for multiple items, overrides item_name/unit_price/quantity: [{"name":"Item","unit_price":1000,"quantity":1}] monthly_installments_enabled: Enable monthly installments monthly_installments_options: Installment options (e.g., [3,6,9,12]) success_url: Redirect URL after successful payment failure_url: Redirect URL after failed payment
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| recurrent | Yes | ||
| expires_at | Yes | ||
| allowed_payment_methods | Yes | ||
| order_template_currency | Yes | ||
| item_name | Yes | ||
| item_unit_price | Yes | ||
| item_quantity | No | ||
| needs_shipping_contact | No | ||
| customer_info_customer_id | No | ||
| customer_info_name | No | ||
| customer_info_email | No | ||
| customer_info_phone | No | ||
| line_items_json | No | ||
| monthly_installments_enabled | No | ||
| monthly_installments_options | No | ||
| success_url | No | ||
| failure_url | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It implies a write operation ('Create') and mentions redirect URLs for payment outcomes, which adds some behavioral context. However, it lacks details on permissions, rate limits, error handling, or what the created checkout looks like (e.g., a link or object). For a mutation tool with zero annotation coverage, this is a moderate 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?
The description is well-structured with a brief purpose statement followed by a parameter list. Each parameter explanation is concise and informative. However, the list is lengthy (18 items), which might overwhelm, but every sentence earns its place by clarifying complex 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?
Given the complexity (18 parameters, 7 required) and no annotations, the description does a good job explaining parameters and implying behavior. An output schema exists, so return values needn't be described. It covers most essentials but could improve by adding usage guidelines and more behavioral details like error cases.
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 0%, so the description must compensate fully. It provides detailed semantics for all 18 parameters, including examples (e.g., 'MXN' for currency, '50000 for $500.00 MXN' for price), defaults, and constraints (e.g., '10 minutes to 365 days from now' for expires_at). This adds significant value beyond the bare 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 clearly states the tool's purpose: 'Create a payment link (checkout).' It specifies the verb ('Create') and resource ('payment link/checkout'), making it unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'create_order' or 'create_subscription', which might also involve payment processing.
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 provides no guidance on when to use this tool versus alternatives like 'create_order' or 'create_subscription'. It lists parameters but doesn't explain prerequisites, typical use cases, or exclusions. Without this context, an agent might struggle to choose between similar payment-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new customer.
Args: name: Customer full name email: Customer email address phone: Customer phone in E.164 format (e.g., +5215555555555) custom_reference: Optional custom reference for your system
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| Yes | |||
| phone | Yes | ||
| custom_reference | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a creation operation, implying mutation, but doesn't cover permissions, side effects, error handling, or response format. The mention of 'custom reference for your system' hints at integration but lacks depth.
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 appropriately sized and front-loaded with the core purpose. The parameter explanations are necessary given low schema coverage, but the formatting with 'Args:' and bullet-like structure is slightly verbose yet still efficient.
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 a mutation tool with no annotations, 0% schema coverage, and an output schema (which reduces need to describe returns), the description covers parameters well but lacks behavioral context like error cases or system impacts. It's minimally adequate but has clear gaps.
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 0%, so the description must compensate fully. It successfully adds meaning beyond the schema by explaining each parameter's purpose and providing a format example for phone ('E.164 format'). This clarifies semantics that the schema alone doesn't capture.
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 action ('Create a new customer') and identifies the resource ('customer'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'update_customer' or 'list_customers', which would require a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'update_customer' or 'list_customers'. It also doesn't mention prerequisites or context for creation, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new order. Provide customer_info_customer_id for an existing customer, or name/email/phone for a new one.
Args: currency: ISO currency code (e.g., MXN, USD) customer_info_customer_id: Existing Conekta customer ID customer_info_name: Customer name (if not using existing customer) customer_info_email: Customer email (if not using existing customer) customer_info_phone: Customer phone E.164 (if not using existing customer) checkout: Checkout object. Supported types: Integration: {"type":"Integration","allowed_payment_methods":["card"],"name":"Pago"} HostedPayment: {"type":"HostedPayment","allowed_payment_methods":["card"],"name":"Pago","success_url":"https://...","failure_url":"https://..."} line_items: Order line items: [{"name":"Item","unit_price":1000,"quantity":1}] charges: Order charges: [{"payment_method":{"type":"card","token_id":"tok_..."}}] shipping_contact: Shipping address: {"address":{"street1":"Nuevo Leon 254","postal_code":"06100","city":"Ciudad de Mexico","state":"Ciudad de Mexico","country":"MX"}} shipping_lines: Order shipping lines: [{"amount":500,"carrier":"FedEx"}] metadata: Metadata object: {"key":"value"}
| Name | Required | Description | Default |
|---|---|---|---|
| currency | Yes | ||
| customer_info_customer_id | No | ||
| customer_info_name | No | ||
| customer_info_email | No | ||
| customer_info_phone | No | ||
| checkout | No | ||
| line_items | No | ||
| charges | No | ||
| shipping_contact | No | ||
| shipping_lines | No | ||
| metadata | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It mentions that the tool creates a new order, implying a write operation, but does not cover critical aspects like authentication needs, rate limits, error handling, or what happens on success (e.g., order ID returned). This leaves significant gaps for an agent to understand the tool's 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?
The description is well-structured with a clear purpose statement followed by an 'Args:' section detailing each parameter. It is appropriately sized for a complex tool, though some sentences could be more concise (e.g., the checkout examples are verbose). Overall, it efficiently conveys necessary information without unnecessary fluff.
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 (11 parameters, no annotations, but with an output schema), the description is partially complete. It excels in parameter semantics but lacks behavioral context (e.g., side effects, error cases). The presence of an output schema means return values need not be explained, but other critical aspects like when to use versus siblings are missing, making it adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description carries the full burden of explaining parameters. It provides detailed semantics for all 11 parameters, including examples for complex objects like 'checkout,' 'line_items,' and 'shipping_contact.' This adds substantial value beyond the bare schema, fully compensating for the lack of schema descriptions.
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's purpose: 'Create a new order.' It specifies the resource (order) and the action (create), which is straightforward. However, it does not explicitly differentiate this from sibling tools like 'create_checkout' or 'create_subscription,' which prevents a perfect score.
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 provides some usage context by explaining how to handle customer information (existing vs. new), but it does not explicitly state when to use this tool versus alternatives like 'create_checkout' or 'create_subscription.' No exclusions or prerequisites are mentioned, leaving gaps in guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a subscription plan.
Args: name: Plan name amount: Plan price in cents currency: ISO currency code (e.g., MXN, USD) interval: Billing interval (day, week, half_month, month, year) frequency: How often the interval repeats (default 1) trial_period_days: Number of trial days before first charge expiry_count: Number of billing cycles before plan expires
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| amount | Yes | ||
| currency | Yes | ||
| interval | Yes | ||
| frequency | No | ||
| trial_period_days | No | ||
| expiry_count | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool creates a plan but lacks details on permissions required, whether the operation is idempotent, error handling, or what happens on success (e.g., plan activation). The description does not add meaningful context beyond the basic action.
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 appropriately sized and front-loaded: the purpose is stated first, followed by a structured list of parameters. Each parameter explanation is concise and directly relevant. However, the formatting with 'Args:' and bullet-like indentation is slightly informal but still clear.
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 no annotations, 7 parameters with 0% schema coverage, and an output schema present, the description is moderately complete. It covers parameter semantics well but lacks behavioral context (e.g., side effects, permissions). The output schema likely handles return values, so the description's focus on inputs is acceptable, but overall completeness is limited by missing usage and transparency details.
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 0%, so the description must compensate. It provides clear semantics for all 7 parameters: name, amount (in cents), currency (ISO code), interval (with examples), frequency (default value), trial_period_days, and expiry_count. This adds significant value beyond the bare schema, explaining units, formats, and defaults.
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's purpose: 'Create a subscription plan.' It specifies the verb ('Create') and resource ('subscription plan'), making the intent unambiguous. However, it does not explicitly differentiate from sibling tools like 'create_checkout' or 'create_order,' which are also creation tools in the same domain.
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 provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., needing a customer or company context), exclusions, or comparisons to siblings like 'create_checkout' or 'create_subscription.' Usage is implied only by the tool's name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a refund for an order.
Args: order_id: The Conekta order ID to refund amount: Refund amount in cents reason: Reason for the refund
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes | ||
| amount | Yes | ||
| reason | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool creates a refund but doesn't cover critical aspects like required permissions, whether the action is reversible, rate limits, or what happens to the order after refund. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
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 appropriately sized and front-loaded, starting with the core purpose followed by parameter explanations. Each sentence adds value without redundancy. However, the parameter section could be more integrated into the flow rather than listed separately, slightly affecting structure.
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 (a mutation with 3 parameters), no annotations, and an output schema (which reduces need to describe return values), the description is minimally adequate. It covers the basic action and parameters but lacks context on usage, behavioral traits, and error handling, leaving gaps for an AI agent.
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 0%, so the schema provides no parameter descriptions. The description adds value by briefly explaining each parameter (e.g., 'order_id: The Conekta order ID to refund'), but it doesn't provide details like format constraints, valid ranges for 'amount', or examples for 'reason'. This partial compensation earns a baseline score.
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's purpose: 'Create a refund for an order.' It specifies the verb ('Create') and resource ('refund for an order'), making it understandable. However, it doesn't explicitly differentiate from sibling tools like 'cancel_order' or 'update_order', which might also modify order states, leaving some ambiguity about when to use this specific tool versus alternatives.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., order must be in a refundable state), exclusions, or comparisons to sibling tools like 'cancel_order' or 'update_order'. This lack of context could lead to misuse by an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a subscription for a customer.
Args: customer_id: The Conekta customer ID plan_id: The plan ID to subscribe to card_id: Payment source ID (uses default if not provided)
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | Yes | ||
| plan_id | Yes | ||
| card_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool creates a subscription, implying a write operation, but doesn't mention permissions, side effects, error handling, or response format. The mention of a default for card_id adds minimal context, leaving critical behavioral traits like idempotency or rate limits unspecified.
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 core purpose in the first sentence, followed by a structured Args section. It avoids redundancy and wastes no words, though the Args formatting could be more integrated. Overall, it's appropriately sized for a 3-parameter tool.
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 3 parameters with 0% schema coverage, no annotations, but an output schema exists, the description is moderately complete. It covers basic parameter semantics and the tool's purpose, but lacks usage guidelines and behavioral details. The output schema likely handles return values, so that gap is mitigated, but overall it's adequate with clear room for improvement.
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 0%, so the description must compensate. It adds meaning by explaining that customer_id is a 'Conekta customer ID', plan_id is for 'the plan to subscribe to', and card_id is a 'Payment source ID' with a default behavior. This clarifies semantics beyond the schema's basic types, but doesn't detail formats, constraints, or examples, leaving gaps for the 3 parameters.
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 action ('Create a subscription') and the target ('for a customer'), which is specific and unambiguous. It distinguishes from siblings like 'create_plan' or 'create_customer' by focusing on subscriptions, though it doesn't explicitly contrast with 'update_subscription' or 'cancel_subscription'.
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 provides no guidance on when to use this tool versus alternatives like 'update_subscription' or 'create_plan'. It mentions a default behavior for card_id, but lacks context on prerequisites, error conditions, or typical workflows, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current account balance.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the basic action. It doesn't disclose whether this is a read-only operation, requires authentication, has rate limits, returns real-time vs. cached data, or what happens on errors. For a financial tool with zero annotation coverage, this is inadequate.
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 a single, clear sentence with no wasted words. It's front-loaded with the essential information and perfectly sized for a simple tool with no 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?
Given the tool's simplicity (0 parameters, output schema exists), the description is minimally adequate but lacks important context. With no annotations and financial data involved, it should mention authentication needs or data freshness. The output schema helps, but behavioral transparency gaps 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?
The tool has 0 parameters with 100% schema description coverage, so the schema fully documents the absence of inputs. The description doesn't need to add parameter information, and appropriately doesn't mention any, earning a high baseline score.
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 action ('Get') and resource ('current account balance'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'list_charges' or 'get_current_company' that might also provide financial information, preventing a perfect score.
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?
No guidance is provided about when to use this tool versus alternatives like 'list_charges' or 'get_current_company', nor are any prerequisites or context for usage mentioned. The description only states what it does, not when it's appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a payment link (checkout) by ID.
Args: checkout_id: The Conekta checkout ID
| Name | Required | Description | Default |
|---|---|---|---|
| checkout_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves a checkout by ID but lacks details on permissions, rate limits, error handling, or response format. While it implies a read operation, it doesn't confirm safety or other behavioral traits beyond the basic action.
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 core purpose in the first sentence, followed by a brief, structured 'Args' section. Every sentence earns its place by directly supporting tool understanding, with no redundant or verbose content. It is appropriately sized for a simple retrieval tool.
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 low complexity (single parameter, no nested objects) and the presence of an output schema (which handles return values), the description is mostly complete. It covers the purpose and parameter semantics well. However, it lacks behavioral details like error cases or usage context, which would be beneficial despite the 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?
The description adds meaningful context for the single parameter 'checkout_id' by specifying it as 'The Conekta checkout ID', which clarifies the expected format and source beyond the schema's minimal title ('Checkout Id'). With 0% schema description coverage and only one parameter, this compensates adequately, though it could provide more detail (e.g., ID format examples).
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 ('Get') and resource ('a payment link (checkout) by ID'), distinguishing it from sibling tools like 'list_checkouts' (which lists multiple) or 'create_checkout' (which creates one). It precisely defines what the tool does without being vague or tautological.
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 provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., needing a checkout ID), exclusions, or comparisons to siblings like 'list_checkouts' for browsing or 'get_order' for related resources. Usage is implied but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current company information associated with the API key.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool retrieves information associated with the API key, implying a read-only operation, but doesn't specify whether it requires authentication, has rate limits, or what happens if no company is linked. This leaves significant gaps for a tool that likely involves sensitive data.
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 a single, efficient sentence that directly states the tool's purpose without any fluff. It's front-loaded and wastes no words, making it easy for an agent to parse quickly.
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 0 parameters, 100% schema coverage, and an output schema exists, the description is minimally adequate. However, it lacks context about authentication needs or error cases, which could be important for an API key-linked tool. The output schema might cover return values, but the description doesn't hint at what 'company information' includes.
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 0 parameters, and the input schema has 100% description coverage (though empty). The description doesn't need to explain parameters, so it meets baseline expectations. No additional parameter information is required or provided.
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's purpose with a specific verb ('Get') and resource ('current company information'), making it easy to understand what it does. However, it doesn't explicitly differentiate from sibling tools like 'get_customer' or 'get_plan', which prevents a perfect score.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., API key context), exclusions, or comparisons to sibling tools, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a customer by ID.
Args: customer_id: The Conekta customer ID (e.g., cus_2tXyF9BwPG14UMkAA)
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the basic action ('Get a customer by ID') without mentioning permissions, rate limits, error handling, or what the output contains. This is insufficient for a tool that likely involves sensitive customer data.
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 core purpose in the first sentence, followed by parameter details in a clear 'Args:' section. It's efficient with no wasted words, though the structure is simple and could be more polished.
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 an output schema (which handles return values) and only one parameter with good semantic coverage in the description, it's minimally adequate. However, the lack of annotations and usage guidelines leaves gaps in understanding behavioral aspects and context.
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 description adds meaningful context for the single parameter: it explains that 'customer_id' is a 'Conekta customer ID' and provides an example format ('cus_2tXyF9BwPG14UMkAA'). Since schema description coverage is 0%, this compensates well, though it could note if the ID is required or sourced from other tools.
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's purpose: 'Get a customer by ID.' It specifies the verb ('Get') and resource ('customer'), making it easy to understand. However, it doesn't differentiate from siblings like 'list_customers' or 'create_customer', which is why it's not a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention siblings like 'list_customers' for multiple customers or 'create_customer' for new ones, nor does it specify prerequisites or exclusions, leaving usage context unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get an event by ID.
Args: event_id: The Conekta event ID
| Name | Required | Description | Default |
|---|---|---|---|
| event_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It states this is a 'Get' operation but doesn't clarify whether it's read-only, requires authentication, has rate limits, or what happens with invalid IDs. For a tool with no annotation coverage, this leaves significant behavioral questions unanswered.
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 appropriately brief with two sentences that directly address the tool's purpose and its single parameter. The 'Args:' section is clearly formatted. However, the second sentence could be more integrated rather than appearing as a separate documentation block.
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 this is a simple retrieval tool with one required parameter and an output schema exists (which handles return values), the description provides adequate context. The combination of clear purpose, parameter explanation, and structured output schema makes this reasonably complete for its complexity level.
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 0%, so the schema provides no parameter documentation. The description adds the parameter name and specifies it's 'The Conekta event ID', which provides essential semantic context beyond the bare schema. However, it doesn't explain format requirements, validation rules, or where to obtain event IDs.
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 action ('Get') and resource ('an event by ID'), making the purpose immediately understandable. It distinguishes this tool from sibling list_events by specifying retrieval of a single event rather than listing multiple events. However, it doesn't fully differentiate from other get_* tools like get_order or get_customer beyond the resource type.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention when to use get_event versus list_events, nor does it specify prerequisites like needing a valid event ID. The agent must infer usage from the tool name and parameter alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get order details by ID.
Args: order_id: The Conekta order ID
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the action ('Get order details'), without mentioning permissions, rate limits, error handling, or what 'details' include. For a read operation with zero annotation coverage, this is insufficient to inform the agent about behavioral traits.
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 concise and front-loaded, with the core purpose stated first and parameter details in a clear 'Args:' section. Both sentences earn their place by providing essential information without redundancy, though minor improvements could enhance readability.
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 simplicity (single parameter, read operation) and the presence of an output schema, the description is reasonably complete. It covers the purpose and parameter semantics adequately, though it lacks usage guidelines and behavioral details that would be helpful for an agent in a context with many sibling tools.
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 description adds meaningful context for the single parameter: it specifies that 'order_id' refers to 'The Conekta order ID', which clarifies the expected format beyond the schema's generic 'string' type. With schema description coverage at 0%, this compensates well, though it doesn't detail constraints like length or pattern.
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's purpose: 'Get order details by ID.' It specifies the verb ('Get') and resource ('order details'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from sibling tools like 'list_orders' or 'update_order', which would require a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'list_orders' for multiple orders or 'update_order' for modifications, nor does it specify prerequisites or exclusions. This leaves the agent without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a subscription plan by ID.
Args: plan_id: The Conekta plan ID
| Name | Required | Description | Default |
|---|---|---|---|
| plan_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves a plan by ID, implying a read-only operation, but doesn't disclose any behavioral traits such as authentication requirements, error handling (e.g., what happens if the plan ID is invalid), rate limits, or response format. This is a significant gap for a tool with no 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?
The description is appropriately sized and front-loaded: the first sentence states the purpose clearly, followed by a brief 'Args' section. There's no wasted text, but the structure could be slightly improved by integrating the parameter info more seamlessly (e.g., as part of the main description).
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 low complexity (1 parameter, no nested objects) and the presence of an output schema (which handles return values), the description is minimally adequate. However, with no annotations and incomplete behavioral disclosure, it lacks context on usage scenarios, error cases, and operational constraints, making it incomplete for safe and effective use by an AI agent.
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 description adds meaningful context for the single parameter: 'plan_id: The Conekta plan ID.' The input schema has 0% description coverage (only titles like 'Plan Id'), so this compensates by specifying the ID is from Conekta and relates to a plan. However, it doesn't provide format details (e.g., string pattern) or examples, leaving some ambiguity.
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's purpose: 'Get a subscription plan by ID.' It specifies the verb ('Get') and resource ('subscription plan'), distinguishing it from siblings like 'list_plans' (which lists multiple plans) and 'create_plan' (which creates a new plan). However, it doesn't explicitly differentiate from other 'get_' tools (e.g., 'get_customer'), though the resource type is clear.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention when to use 'get_plan' instead of 'list_plans' (e.g., for retrieving details of a specific known plan ID) or any prerequisites (e.g., needing a valid plan ID). The context is implied but not stated explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get subscription details.
Args: customer_id: The Conekta customer ID subscription_id: The subscription ID
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | Yes | ||
| subscription_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. While 'Get' implies a read-only operation, it doesn't disclose authentication requirements, rate limits, error conditions, or what happens if IDs are invalid. The description doesn't mention that this is a safe read operation or provide any behavioral context beyond the basic action.
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 appropriately concise with a clear purpose statement followed by parameter explanations. The two-sentence structure is efficient with minimal waste. However, the parameter documentation could be integrated more smoothly rather than as a separate 'Args:' section.
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 that an output schema exists (which will document return values), the description doesn't need to explain return format. However, for a tool with 2 required parameters, 0% schema description coverage, and no annotations, the description should provide more context about authentication, error handling, and relationship to sibling tools. The current description is minimally adequate but has clear gaps.
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 0%, so the schema provides no parameter documentation. The description adds basic semantics by explaining that 'customer_id' is 'The Conekta customer ID' and 'subscription_id' is 'The subscription ID', which clarifies what these identifiers represent. However, it doesn't provide format examples, validation rules, or where to find these IDs.
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's purpose as 'Get subscription details' which is a specific verb+resource combination. It distinguishes itself from sibling tools like 'list_subscriptions' (which returns multiple) and 'create_subscription' (which creates new ones). However, it doesn't explicitly contrast with 'update_subscription' or 'cancel_subscription' which might also return details.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention when to use 'get_subscription' versus 'list_subscriptions' (for multiple subscriptions) or 'get_customer' (which might include subscription info). No prerequisites, exclusions, or contextual recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all charges with optional search and pagination.
Args: limit: Max charges to return (1-250, default 20) search: Search filter next_page: Cursor for next page previous_page: Cursor for previous page
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| search | No | ||
| next_page | No | ||
| previous_page | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions pagination and search capabilities, but doesn't describe authentication needs, rate limits, error conditions, or what 'charges' represent in this context. It lacks details on response format, data freshness, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded with the core purpose in the first sentence. The parameter explanations are organized in a clear Args section. There's minimal waste, though the formatting could be slightly more polished.
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 4 parameters with 0% schema coverage and no annotations, the description does well on parameters but lacks behavioral context. The existence of an output schema means return values don't need explanation, but authentication, error handling, and usage context gaps remain. Adequate but with clear gaps.
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 0%, so the description must compensate. It provides meaningful semantics for all 4 parameters: explains 'limit' range and default, describes 'search' as a filter, and clarifies 'next_page'/'previous_page' as pagination cursors. This adds significant value beyond the bare 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 clearly states the tool's purpose: 'List all charges with optional search and pagination.' It specifies the verb ('List') and resource ('charges'), and mentions key capabilities (search, pagination). However, it doesn't explicitly differentiate from sibling tools like 'list_orders' or 'list_subscriptions' beyond the resource name.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, context for use, or compare it to sibling list tools (e.g., list_orders, list_subscriptions). Usage is implied by the name but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List payment links (checkouts) with optional search and pagination.
Args: limit: Max checkouts to return (1-250, default 20) search: Search filter next_page: Cursor for next page previous_page: Cursor for previous page
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| search | No | ||
| next_page | No | ||
| previous_page | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions 'optional search and pagination' which gives some behavioral context, but doesn't disclose important traits like whether this is a read-only operation, authentication requirements, rate limits, error conditions, or what the output looks like. For a list operation with no annotation coverage, this is inadequate.
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 appropriately sized and well-structured with a clear purpose statement followed by parameter explanations. Every sentence adds value, though the formatting with 'Args:' could be slightly more polished. It's front-loaded with the core functionality.
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 that there's an output schema (which handles return values), 0 required parameters, and the description covers all parameter semantics, this is reasonably complete for a list operation. However, the lack of behavioral transparency (no annotations, no disclosure of read/write nature, auth needs, etc.) prevents a higher score.
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 0% schema description coverage, the description fully compensates by providing clear semantic information for all 4 parameters. It explains what each parameter does (limit: 'Max checkouts to return', search: 'Search filter', next_page/previous_page: 'Cursor for next/previous page'), including the limit range (1-250) and default value (20) that aren't in 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 clearly states the tool's purpose as 'List payment links (checkouts) with optional search and pagination.' This specifies the verb ('List'), resource ('payment links/checkouts'), and scope ('with optional search and pagination'). However, it doesn't explicitly differentiate from sibling tools like 'get_checkout' or 'list_orders', which would require a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There are multiple sibling tools (e.g., 'get_checkout' for a single checkout, 'list_orders' for orders), but the description doesn't mention any of them or provide context about when this tool is appropriate versus others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List customers with optional search and pagination.
Args: limit: Max number of customers to return (1-250, default 20) search: Search by name, email, phone, or custom reference next_page: Cursor for next page (from previous response) previous_page: Cursor for previous page (from previous response)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| search | No | ||
| next_page | No | ||
| previous_page | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions pagination behavior (cursors for next/previous pages) which is valuable, but doesn't disclose other important traits: whether this is a read-only operation, authentication requirements, rate limits, error conditions, or what the response structure looks like. For a listing tool with no annotations, this leaves significant behavioral gaps.
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 perfectly structured and concise. The first sentence states the core purpose, followed by a well-organized 'Args:' section with bullet-like clarity. Every sentence earns its place, with no wasted words or redundancy. The information is front-loaded with the most important purpose statement first.
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 that there's an output schema (mentioned in context signals), the description doesn't need to explain return values. The parameter semantics are fully covered, and the purpose is clear. However, for a tool with no annotations and multiple sibling tools, it could benefit from more behavioral context and usage guidance to be fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate - which it does excellently. The 'Args:' section provides complete semantic documentation for all 4 parameters: 'limit' with range and default, 'search' with what fields it searches, and 'next_page'/'previous_page' explaining they're cursors from previous responses. This adds substantial value beyond the bare 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 clearly states the tool's purpose: 'List customers with optional search and pagination.' It specifies the verb ('List') and resource ('customers'), and mentions key capabilities (search, pagination). However, it doesn't explicitly differentiate from sibling tools like 'get_customer' or 'list_orders', which would be needed for a perfect score.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'get_customer' (for retrieving a single customer) or explain when search/pagination is appropriate versus other listing tools. The only implicit guidance is that it's for listing customers, but no explicit usage context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List system events with pagination.
Args: limit: Max events to return (1-250, default 20) next_page: Cursor for next page previous_page: Cursor for previous page
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| next_page | No | ||
| previous_page | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses pagination behavior, which is valuable, but doesn't mention authentication requirements, rate limits, error conditions, or what 'system events' encompass. It adequately describes the core operation but lacks comprehensive behavioral context.
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 core purpose, followed by a structured Args section. Every sentence adds value without redundancy, making it efficient and well-organized for quick comprehension.
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 no annotations, 0% schema coverage, but an output schema exists, the description covers the essential operation and parameters adequately. It could improve by clarifying the nature of 'system events' or linking to sibling tools, but it's largely complete for a list tool with pagination.
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 0%, so the description must compensate. It adds meaningful semantics for all three parameters: 'limit' specifies range and default, 'next_page' and 'previous_page' explain their role in pagination. This goes beyond the bare schema, though it could detail cursor format or pagination mechanics more.
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 verb ('List') and resource ('system events'), making the purpose specific and understandable. However, it doesn't differentiate from sibling tools like 'get_event' or 'list_orders', which would require more explicit scope definition.
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?
No guidance is provided on when to use this tool versus alternatives like 'get_event' or other list tools. The description mentions pagination but doesn't explain when pagination is needed or how it relates to sibling operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List orders with optional filters and pagination.
Args: limit: Max orders to return (1-250, default 20) search: Search by email, reference, etc. payment_status: Filter by status (paid, pending, refunded, etc.) next_page: Cursor for next page previous_page: Cursor for previous page
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| search | No | ||
| payment_status | No | ||
| next_page | No | ||
| previous_page | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions pagination behavior (cursors for next/previous pages) which is valuable, but doesn't disclose other important traits: whether this requires authentication, rate limits, what happens on errors, or the format/structure of returned orders. For a list operation with no annotation coverage, this leaves significant behavioral gaps.
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 well-structured with a clear purpose statement followed by parameter details. Every sentence earns its place by providing essential information. It could be slightly more front-loaded with key behavioral context, but overall it's efficient with minimal waste.
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 moderate complexity (list operation with 5 parameters), no annotations, but with an output schema present, the description is partially complete. It excels at parameter semantics but lacks behavioral context (auth, errors, rate limits) and doesn't mention the existence of an output schema. For a tool with siblings and no annotations, it should provide more contextual guidance.
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 0%, so the description must compensate fully. It provides excellent parameter semantics: explains 'limit' range and default, clarifies 'search' scope (email, reference), enumerates 'payment_status' values (paid, pending, refunded), and explains cursor parameters for pagination. This adds substantial meaning beyond the bare 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 clearly states the tool's purpose: 'List orders with optional filters and pagination.' It specifies the verb ('List') and resource ('orders'), and mentions key capabilities (filtering, pagination). However, it doesn't explicitly differentiate from sibling tools like 'get_order' (singular retrieval) or 'list_charges' (different resource), which prevents a perfect score.
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 provides no guidance on when to use this tool versus alternatives. With siblings like 'get_order' (singular retrieval) and 'list_charges' (different resource type), the agent receives no help in choosing between them. The description only explains what the tool does, not when it's appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List subscription plans with optional search and pagination.
Args: limit: Max plans to return (1-250, default 20) search: Search by plan name next_page: Cursor for next page previous_page: Cursor for previous page
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| search | No | ||
| next_page | No | ||
| previous_page | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions pagination and search features, which adds some context, but fails to describe key behaviors such as rate limits, authentication requirements, error handling, or the structure of returned data. For a read operation with no annotation coverage, this leaves significant gaps.
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 well-structured and front-loaded with the core purpose, followed by a clear breakdown of parameters. Every sentence earns its place by providing essential information without redundancy, making it efficient and easy to parse.
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 (a list operation with pagination and search), no annotations, and an output schema (which handles return values), the description is largely complete. It covers the purpose and parameters well but lacks behavioral details like rate limits or auth needs, which are important for a read tool in a billing context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate fully. It provides detailed semantics for all four parameters (limit, search, next_page, previous_page), including ranges, defaults, and purposes. This adds substantial value beyond the bare schema, effectively documenting parameter usage.
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's purpose with a specific verb ('List') and resource ('subscription plans'), and distinguishes it from sibling tools like 'get_plan' (which retrieves a single plan) and 'create_plan' (which creates a plan). It also mentions optional search and pagination features, adding specificity.
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 for listing plans with optional filtering and pagination, but does not explicitly state when to use this tool versus alternatives like 'get_plan' for a single plan or 'list_subscriptions' for subscriptions. It provides basic context but lacks explicit guidance on exclusions or comparisons with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List subscriptions for a customer.
Args: customer_id: The Conekta customer ID limit: Max subscriptions to return (1-250, default 20) next_page: Cursor for next page previous_page: Cursor for previous page
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | Yes | ||
| limit | No | ||
| next_page | No | ||
| previous_page | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. While it mentions pagination parameters ('next_page', 'previous_page'), it doesn't describe the tool's behavior regarding rate limits, authentication requirements, error conditions, or what happens when no subscriptions exist for a customer. The description lacks crucial operational context for a listing tool with pagination capabilities.
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 well-structured with a clear purpose statement followed by organized parameter documentation. The Args section uses bullet-like formatting that's easy to parse. While efficient, the purpose statement could be slightly more informative about the tool's scope or typical use cases to be perfectly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there's an output schema (which handles return values), no annotations, and 4 parameters with good documentation in the description, the description is moderately complete. However, for a listing tool with pagination, it should ideally mention typical response structure or behavior patterns. The description covers the basics but lacks operational context that would help an agent use it effectively.
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 description provides detailed parameter information in the Args section, including the purpose of each parameter, range constraints for 'limit' (1-250), and default values. With 0% schema description coverage, this parameter documentation in the description fully compensates for the schema's lack of descriptions. The only minor gap is not explicitly stating that 'customer_id' is required, though this is clear from the schema's required field.
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's purpose: 'List subscriptions for a customer.' It specifies the verb ('List') and resource ('subscriptions') with a scope ('for a customer'). However, it doesn't explicitly differentiate from sibling tools like 'get_subscription' or 'list_customers', which would require more specific context about what makes this listing operation unique.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'get_subscription' (for single subscription details) or 'list_customers' (for listing customers instead of their subscriptions). There's no context about prerequisites, typical use cases, or when this tool is preferred over other listing operations in the system.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pause a subscription.
Args: customer_id: The Conekta customer ID subscription_id: The subscription ID to pause
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | Yes | ||
| subscription_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the action ('Pause a subscription') but doesn't explain what pausing entails—whether it's reversible, affects billing, requires specific permissions, or has side effects. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
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 appropriately sized and front-loaded with the core purpose. The two-sentence structure is efficient, though the parameter explanations could be slightly more informative without sacrificing conciseness.
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 (a mutation operation), lack of annotations, and 0% schema description coverage, the description is incomplete. It covers the basic action and parameters but misses critical context like behavioral effects, prerequisites, and differentiation from siblings. The presence of an output schema helps, but the description should do more to compensate for missing structured data.
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 0%, so the description must compensate. It lists both parameters with brief explanations ('The Conekta customer ID', 'The subscription ID to pause'), adding basic semantics beyond the schema's titles. However, it doesn't provide format details, validation rules, or examples, leaving gaps in parameter understanding.
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 verb ('Pause') and resource ('a subscription'), making the tool's purpose immediately understandable. However, it doesn't differentiate itself from sibling tools like 'cancel_subscription' or 'resume_subscription', which would require more specific language about what pausing entails versus those alternatives.
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 provides no guidance on when to use this tool versus alternatives like 'cancel_subscription' or 'resume_subscription'. It doesn't mention prerequisites, consequences, or appropriate contexts for pausing a subscription, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resume a paused subscription.
Args: customer_id: The Conekta customer ID subscription_id: The subscription ID to resume
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | Yes | ||
| subscription_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the action ('Resume') but lacks critical behavioral details: whether this requires specific permissions, if it's reversible, what happens upon resumption (e.g., billing restart, service reactivation), rate limits, or error conditions. The description is minimal and misses key operational context.
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 core purpose in the first sentence, followed by parameter details. It's appropriately sized with no redundant information. However, the parameter section could be integrated more seamlessly, and the lack of behavioral details means it's concise but potentially under-specified.
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 2 parameters with 0% schema coverage, no annotations, and an output schema (which reduces need to describe returns), the description is minimally adequate. It covers the basic action and parameters but lacks context on prerequisites, effects, and error handling, making it incomplete for safe and effective use without additional 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 description coverage is 0%, so the description must compensate. It lists both parameters with brief explanations ('Conekta customer ID', 'subscription ID to resume'), adding basic semantics beyond the schema's titles. However, it doesn't clarify format (e.g., ID structure), sourcing (e.g., from get_subscription), or validation rules, leaving gaps in understanding.
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 verb ('Resume') and resource ('a paused subscription'), making the purpose immediately understandable. It distinguishes from siblings like 'pause_subscription' and 'cancel_subscription' by specifying the action. However, it doesn't explicitly mention what 'resume' entails (e.g., restarting billing, reactivating services), which prevents a perfect score.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., subscription must be paused), exclusions (e.g., cannot resume canceled subscriptions), or compare with siblings like 'update_subscription' for other modifications. Usage is implied but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a payment link via email.
Args: checkout_id: The Conekta checkout ID email: Recipient email address
| Name | Required | Description | Default |
|---|---|---|---|
| checkout_id | Yes | ||
| Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the action but doesn't disclose behavioral traits like whether this sends an actual email (external side effect), requires specific permissions, has rate limits, or what happens on failure. The description is minimal and lacks operational context.
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 appropriately sized with a clear purpose statement followed by parameter explanations. The two-sentence structure is efficient, though the parameter section could be integrated more smoothly. No wasted words, but slightly fragmented.
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 2 parameters with 0% schema coverage and an output schema (which reduces need to describe returns), the description is moderately complete. It covers the basics but lacks details on behavior, error handling, and integration context. For a tool with external effects (sending email), more completeness is warranted.
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 0%, so the description must compensate. It lists both parameters with brief explanations ('The Conekta checkout ID', 'Recipient email address'), adding basic meaning beyond the schema's titles. However, it doesn't provide format details (e.g., email validation, checkout ID format) or constraints, leaving gaps.
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 action ('Send a payment link via email') and identifies the resource (payment link associated with a checkout). It distinguishes from sibling 'send_checkout_sms' by specifying email delivery, but doesn't explain how it differs from other checkout-related tools like 'get_checkout' or 'create_checkout'.
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?
No guidance on when to use this tool versus alternatives is provided. The description doesn't mention prerequisites (e.g., needing an existing checkout), appropriate contexts, or when other tools like 'send_checkout_sms' might be preferable. Usage is implied but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a payment link via SMS.
Args: checkout_id: The Conekta checkout ID phone: Recipient phone number in E.164 format
| Name | Required | Description | Default |
|---|---|---|---|
| checkout_id | Yes | ||
| phone | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Send a payment link via SMS') but does not cover critical aspects like whether this is a mutation (likely yes, but unconfirmed), authentication needs, rate limits, error handling, or what the SMS content includes. This leaves significant gaps for an agent to understand the tool's 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?
The description is front-loaded with the core purpose in the first sentence, followed by a structured 'Args:' section that efficiently lists parameters. It avoids unnecessary details, though the 'Args:' formatting is slightly verbose; overall, it is appropriately sized with minimal waste.
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 (a mutation with 2 parameters, no annotations, but an output schema exists), the description is moderately complete. It covers the purpose and parameter semantics adequately, but lacks behavioral context and usage guidelines. The presence of an output schema means return values need not be explained, but other gaps remain, making it just adequate for basic 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?
The description adds meaningful semantics beyond the input schema, which has 0% description coverage. It explains that 'checkout_id' corresponds to a 'Conekta checkout ID' (implying a payment link) and specifies the format for 'phone' ('E.164 format'), clarifying usage that the schema alone does not provide. This compensates well for the low schema coverage, though it could detail the SMS content or link behavior further.
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 ('Send a payment link via SMS') and identifies the resource ('payment link' via 'checkout_id'), distinguishing it from siblings like 'send_checkout_email' by specifying the SMS channel. It uses a precise verb ('Send') and resource type, making 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 provides no guidance on when to use this tool versus alternatives, such as 'send_checkout_email' for email-based delivery or other checkout-related tools. It lacks context about prerequisites, timing, or exclusions, offering only basic parameter information without usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing customer. Only provided fields are updated.
Args: customer_id: The Conekta customer ID name: New customer name email: New customer email phone: New customer phone custom_reference: New custom reference
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | Yes | ||
| name | No | ||
| No | |||
| phone | No | ||
| custom_reference | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states 'Only provided fields are updated' which is useful behavioral context about partial updates. However, it lacks critical information: authentication requirements, rate limits, error conditions, whether the operation is idempotent, or what happens if invalid data is provided. For a mutation tool with zero annotation coverage, this is insufficient.
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 appropriately sized and front-loaded with the core purpose in the first sentence. The parameter list is organized but could be more integrated. No wasted sentences, though the 'Args:' section formatting is slightly redundant with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a mutation tool with no annotations, 5 parameters (1 required), 0% schema coverage, but with an output schema, the description is minimally adequate. It covers the partial update behavior and parameter meanings but lacks important context about authentication, errors, and system behavior. The output schema existence reduces the need to describe return values.
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 0%, so the description must compensate. It lists all 5 parameters with brief explanations, adding meaning beyond the bare schema. The description clarifies that customer_id identifies the target and other fields represent new values. However, it doesn't explain format constraints (e.g., email validation) or the implications of null values.
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 'Update an existing customer' which specifies the verb (update) and resource (customer). It distinguishes from siblings like create_customer (creation vs. update) and get_customer (read vs. write). However, it doesn't explicitly differentiate from other update tools like update_order or update_subscription beyond the resource name.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing customer_id), when not to use it (e.g., for creating new customers), or compare it to related tools like create_customer or get_customer. The agent must infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing order.
Args: order_id: The Conekta order ID metadata: Metadata object to update: {"key":"value"}
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes | ||
| metadata | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is an update operation (implying mutation) but doesn't mention required permissions, whether changes are reversible, rate limits, or what happens to existing order data not mentioned. The description lacks critical behavioral context for a mutation tool.
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 appropriately brief and front-loaded with the core purpose. The two-sentence structure with a clear header for arguments is efficient. However, the metadata example '{"key":"value"}' is minimal and could be more informative without sacrificing conciseness.
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 an output schema (which handles return values), no annotations, and low schema coverage, the description is moderately complete. It covers the basic purpose and parameters but lacks behavioral details, usage context, and deeper parameter semantics. For a mutation tool with 2 parameters, this leaves room for improvement in guiding the agent.
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 0%, so the schema provides no parameter documentation. The description adds basic semantics for both parameters: 'order_id' identifies the target order, and 'metadata' is an object with key-value pairs. However, it doesn't explain metadata constraints, format examples, or how updates merge with existing data, leaving significant gaps.
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 action ('Update') and target resource ('an existing order'), making the purpose immediately understandable. It distinguishes this from sibling tools like 'create_order' or 'cancel_order' by focusing on modification rather than creation or cancellation. However, it doesn't specify what aspects of an order can be updated beyond metadata.
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 provides no guidance on when to use this tool versus alternatives like 'update_customer' or 'update_subscription'. It doesn't mention prerequisites (e.g., needing an existing order ID), nor does it clarify use cases or constraints compared to other order-related tools like 'capture_order' or 'cancel_order'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a subscription.
Args: customer_id: The Conekta customer ID subscription_id: The subscription ID plan_id: New plan ID card_id: New payment source ID
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | Yes | ||
| subscription_id | Yes | ||
| plan_id | No | ||
| card_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. While 'Update' implies a mutation, the description doesn't specify whether this requires specific permissions, what happens to existing subscription settings not mentioned (e.g., billing cycle), whether changes are reversible, or any rate limits. It mentions 'New plan ID' and 'New payment source ID' but doesn't clarify if these replace existing values or are optional updates.
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 appropriately sized with a clear purpose statement followed by parameter details. The 'Args:' section is structured but could be more front-loaded with key behavioral information. No sentences are wasted, though it could be more efficient by integrating parameter semantics into the main description.
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 that annotations are absent, schema coverage is 0%, and an output schema exists (reducing need to describe returns), the description is moderately complete. It covers the basic purpose and parameters but lacks crucial context for a mutation tool: no error handling, side effects, or integration with sibling tools. For a subscription update with financial implications, this is a significant 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 description coverage is 0%, so the description must compensate. It lists all four parameters with brief explanations, adding meaning beyond the schema's titles (e.g., 'Conekta customer ID' specifies the system). However, it doesn't explain that plan_id and card_id are optional (as indicated by null defaults in schema) or provide format examples, leaving gaps in understanding.
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 verb ('Update') and resource ('a subscription'), making the purpose immediately understandable. However, it doesn't differentiate this tool from sibling tools like 'update_customer' or 'update_order' beyond the resource name, and it doesn't specify what aspects of a subscription can be updated beyond what's implied by the parameters.
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 provides no guidance on when to use this tool versus alternatives like 'cancel_subscription', 'pause_subscription', or 'resume_subscription'. It doesn't mention prerequisites (e.g., that a subscription must exist) or contextual constraints, leaving the agent to infer usage from the tool name and parameters alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.3.0cancel_checkoutcancel_ordercancel_subscriptioncapture_ordercreate_checkoutcreate_customercreate_ordercreate_plancreate_refundcreate_subscriptionget_balanceget_checkoutget_current_companyget_customerget_eventget_orderget_planget_subscriptionlist_chargeslist_checkoutslist_customerslist_eventslist_orderslist_planslist_subscriptionspause_subscriptionresume_subscriptionsend_checkout_emailsend_checkout_smsupdate_customerupdate_orderupdate_subscriptionScored across 32 tools
Every tool has a clearly distinct purpose targeting specific resources and actions in the Conekta payment processing domain. For example, cancel_checkout, cancel_order, and cancel_subscription each handle different resource types, while create_checkout and create_order serve distinct payment flow purposes. There is no overlap or ambiguity between tools.
Tool names follow a perfectly consistent verb_noun pattern throughout the entire set. All 32 tools use this convention (e.g., create_customer, get_balance, list_orders, update_subscription) with no deviations in style or structure. The naming is predictable and easily parsable.
With 32 tools, this server feels overly heavy for a payment processing API. While the domain is complex, many tools could potentially be consolidated (e.g., send_checkout_email and send_checkout_sms could be a single tool with a channel parameter). The count exceeds the typical well-scoped range of 3-15 tools and may overwhelm agents.
The tool surface provides comprehensive CRUD/lifecycle coverage for all major Conekta entities: customers, orders, checkouts, subscriptions, plans, charges, and events. Every resource has create, get, list, and update/delete/cancel operations where applicable, plus specialized actions like capture, refund, pause/resume, and notification sending. There are no obvious gaps.
Read payment settings, orders and receipts, create payment links and API keys.
Create and manage checkout pages, event ticketing, forms, customers, payments and subscriptions.
Query and manage Mercoa AP/AR bill-pay: entities, invoices, transactions and payment methods.
Create payment orders, checkout, subscriptions & UPI via PineLabs Plural PG gateway
