Kapruka MCP

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

The description goes well beyond the annotations (readOnlyHint=true, destructiveHint=false). It discloses the flat-rate-per-order behavior ('single shipment per order at one flat rate regardless of item count'), the perishable warning logic, and the default date behavior ('defaults to today (LK time)'). It also details the exact JSON response schema, including null fields and conditions. With annotations already establishing safety, this extra context is valuable and non-redundant.

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 clear 'Args' and 'Returns' sections, and the core purpose is front-loaded. It is slightly longer than necessary but every sentence adds useful detail—no filler. The JSON schema example is appropriately compact and aids 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?

The description is highly complete given the tool's complexity. The output schema is fully explained, return fields are enumerated with conditions, perishable warning behavior is described, and defaults are specified. There is no ambiguity about the response format or edge cases. Sibling tools exist but do not create a need for more context here.

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's Args section explicitly lists and explains each parameter in plain language, complementing the schema which also has descriptions. It adds meaning beyond the schema by explaining the effect of product_id ('enables perishable warning') and the default behavior of delivery_date. The flat-rate note and perishable logic give real semantic depth beyond field names and types.

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

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

The description opens with a specific verb+resource+scope: 'Check whether Kapruka can deliver to a given city on a given date, and at what rate.' It clearly differentiates from sibling tools like kapruka_list_delivery_cities (which lists cities) and kapruka_create_order (which places orders). The purpose is unambiguous and immediately actionable.

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 clear context for when to use the tool (checking delivery feasibility and rate) and includes conditional usage guidance: 'If a product_id is supplied and the code matches a perishable family... the chosen delivery date is more than 1 day out.' It does not explicitly mention alternatives or exclusions, but the context is sufficient. A minor gap is not referencing sibling tools like kapruka_list_delivery_cities for city discovery, though the schema covers that.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description reveals vital behaviors: prices locked for 60 minutes, free tier limits (30 orders/hour/IP), cart and quantity limits, idempotency key generation for retries, and guest checkout without an account. It also documents error message format and common error codes. There is no contradiction with annotations.

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

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

The description is long but well-organized into sections (summary, limits, args, returns, errors). Every sentence provides actionable information, with the core purpose front-loaded and supporting details logically grouped. No redundant or filler content.

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

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

This is a complex tool with nested parameters and multiple constraints, yet the description covers all essential aspects: input structure, validation rules, error handling, return JSON schema, and behavioral semantics like pricing and idempotency. It is fully self-contained and leaves no critical gaps for an AI agent to invoke the tool correctly.

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

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

The Args section paraphrases and enriches each schema field with practical meaning, such as phone format (E.164 +9477… or local 077…), icing_text only for cakes, and city must be Kapruka-deliverable. It also clarifies the response_format options and supported currencies, going well beyond the raw 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 opens with 'Create a guest-checkout order on Kapruka and return a click-to-pay link,' clearly stating the verb, resource, and outcome. It distinguishes itself from sibling tools by focusing on order creation rather than listing, searching, or tracking, leaving no ambiguity about its function.

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

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

The description explicitly explains when to use the tool and how to prepare inputs, including a cross-reference to kapruka_list_delivery_cities for valid city names. It also states constraints like 'No Kapruka account is required' and delivery date must be today or future, providing clear context for correct usage. While it doesn't list exclusions for sibling tools, its role is unambiguous.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: the CATSYM category landing page edge case, optional currency conversion, response format selection, error string format, and a complete JSON schema of the returned data. This goes well beyond what the annotations provide.

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

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

The description is well-structured with a clear purpose, a note, an Args section, and a Returns section with the full JSON schema. Every part adds necessary detail, and the information is front-loaded with the main purpose in the first sentence. No filler or repetition exists.

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?

The description is fully self-contained for a complex tool: it covers all four parameters, provides a complete output schema, explains error handling, and notes the CATSYM edge case. Combined with the annotations, the agent has everything needed to select and invoke the tool correctly without external documentation.

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

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

The input schema already thoroughly describes each parameter (product_id format, currency options, type hint, response_format meaning). The description's Args section largely repeats this information without adding significant new semantics, though it does present the nesting under 'params' clearly. Given high schema coverage, a baseline score of 3 is appropriate.

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

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

The description opens with 'Fetch full details for a single Kapruka product by its product ID', using a specific verb and resource with clear scope. It distinguishes from siblings like search_products and list_categories by focusing on a single product via ID, and lists the exact data fields returned.

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 clearly implies this is for retrieving a specific product when you already have its ID, and the note about CATSYM IDs warns against using it for category landing pages. However, it does not explicitly name alternative tools like kapruka_search_products for discovery, so it lacks explicit when-not-to-use guidance.

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

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

Beyond annotations (readOnlyHint, etc.), the description discloses that 'Internal IDs and product counts are not exposed' and 'Results are cached for 30 minutes server-side.' It also details the error format, adding valuable 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 well-structured with a clear summary, Args, Returns, and error format. It is slightly long due to the embedded JSON schema, but each section contributes to usability.

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?

All relevant aspects are covered: purpose, parameter semantics, output schema, limitations, caching, and error handling. The cross-reference to kapruka_search_products aids contextual understanding within the sibling set.

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's Args section restates the schema's parameter descriptions without adding new meaning. The schema already fully documents depth and response_format, so the baseline of 3 applies.

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

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

The description clearly states the tool's function: 'List top-level Kapruka product categories by name with browse URLs.' It also distinguishes itself from siblings by noting the returned names are usable as a filter on kapruka_search_products, making its purpose specific and non-overlapping.

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?

Guidance is provided: 'useful for shopping agents that want to send users directly to a category to browse' and relationships to kapruka_search_products are mentioned. While it doesn't explicitly state when not to use it, the context strongly implies its role versus searching.

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

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

Adds substantial behavioral detail beyond annotations: default shows first 25 cities alphabetically, query enables partial case-insensitive match, response_format can be markdown or json, and returns canonical names plus aliases. The caveat about the default being rarely needed is honest and useful.

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

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

Well-structured and front-loaded: opening purpose, usage guidance, Args section, and Returns with JSON schema. Each sentence contributes relevant information without unnecessary verbosity.

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 list/search functionality and available output schema, the description covers default behavior, filtering, response formats, and return structure. It even includes a JSON schema excerpt, making it complete for an agent to call correctly.

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

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

The description restates parameter names and types, but also adds illustrative examples and meaning beyond the schema. It explains the query behavior with concrete examples and clarifies that returned names should be used as the `city` argument, enriching parameter semantics.

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?

Clearly states it lists or searches Sri Lankan cities Kapruka delivers to, with a specific verb (list/search) and resource (cities). It distinguishes from sibling kapruka_check_delivery by noting it returns canonical city names to use as the `city` argument for that tool.

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

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

Provides explicit usage guidance: warns that without a query the default alphabetical limit is rarely what an agent needs, and gives example filters ('colombo' → Colombo zones, 'anur' → Anuradhapura). It implies the relationship to kapruka_check_delivery but does not state when to avoid using this tool.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description reveals that the image is server-composited from live catalog data (so prices match product tools), explains the ref-assignment contract (sequential, never reused, stable meaning per conversation), and details the exact JSON return shape and error behavior. These are operational traits the annotations do not cover.

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 longer than average but every part is warranted: it front-loads the purpose, then explains the chat use case, the critical ref contract, and ends with organized Args/Returns sections. It is structured and free of fluff—no sentence is redundant with the annotations or 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?

The tool's behavior is complex enough that this detail is needed: it specifies the output URL, the item list with product names, prices, and URLs, the absence of unavailable products, and the fallback error string. Together with the WhatsApp scenario and the ref contract, the description provides complete context for an agent to invoke it correctly.

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

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

With schema_description_coverage at 0% for the top-level 'params' parameter, the description's Args section compensates fully: it lists 'items' (1-4 of {product_id, ref}) and 'currency' with defaults, clarifies the ref numbering rule, and gives an example of use. This adds practical meaning well beyond the bare schema structure.

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

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

The description opens with a precise action and outcome: 'Render 1-4 products as ONE shareable JPEG "menu" card and return its URL.' This clearly differentiates the tool from siblings (search, create_order, delivery) by its output format (a composited image card) and its chat-commerce purpose.

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

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

The description explicitly targets a WhatsApp chat-commerce use case: 'send the image, tell the customer "reply 1, 2 or 3" and they pick without opening links.' This provides clear when-to-use context, but it does not name alternative tools or state exclusions, so it misses the top score by one.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavioral context: pagination is capped at 3 pages, queries must be ≥3 chars and reject stopwords, category landing pages (price=0) are filtered by default, and error formats are specified. This goes well beyond the annotations.

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

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

The description is long but every section earns its place: purpose first, then pagination and query rules, then a structured Args list, then the return JSON schema and error messages. It is front-loaded with the most important info and contains no 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?

The description fully covers the complexity of this search tool: pagination behavior and cap, query constraints, stub filtering, parameter meanings, and the complete output schema. It also documents error strings and the special meaning of next_cursor. Nothing important is left unexplained.

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 at the top level is 0% (the 'params' property has no description), so the description must compensate. It does so thoroughly: the Args section lists all 11 parameters with types, defaults, allowed values, and examples (e.g., sort options, currency list, min price). This adds critical 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 opens with 'Search for products on Kapruka.com by keyword, with optional category filter and pagination,' using a specific verb+resource+scope. This clearly distinguishes it from sibling tools like kapruka_get_product (single product) and kapruka_list_categories.

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

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

Provides clear context for usage: keyword search, cursor-based pagination, pagination cap of 3 pages, and advice to 'refine the query or filter by category instead' for broader discovery. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of a 5.

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

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

The description goes far beyond the annotations by detailing the exact statuses returned, the contents of the progress timeline, availability of delivery photo/video flags, and the error message format. Even though readOnlyHint and destructiveHint are already provided, the description adds meaningful behavioral context (e.g., live_tracking_available boolean, payment reference field) that helps an agent anticipate results.

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

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

The description is well-organized: it starts with the core purpose, provides usage context, lists parameters, and includes a return schema. Every sentence contributes value, and the structure makes it easy to scan. The embedded JSON schema is verbose but justified given the complex return payload.

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 (multiple statuses, nested recipient/items objects, error handling), the description is comprehensive. It explains when to use it, what input to provide, what output to expect, and includes the caveat about order_ref. The annotations and detailed schema round out the context, making the tool fully actionable.

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's Args section essentially mirrors the input schema, which already contains detailed descriptions for both parameters, including the crucial order_ref distinction. Thus, the description adds little new semantic meaning beyond what the schema provides. The example format ('VIMP34456CB2') is helpful but not a significant increment.

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 uses a specific verb ('Look up') and resource ('status and delivery progress for a Kapruka order by order number'), clearly distinguishing it from sibling tools like kapruka_create_order. It also outlines the exact output, making the purpose unmistakable.

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

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

It explicitly states when to use the tool ('after a customer has placed and paid for an order and reads back the order number from their confirmation email or the order complete page') and warns against using the order_ref from kapruka_create_order. This provides clear when-to-use and when-not-to-use guidance, effectively differentiating it from related tools.

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