Verified ROKI Connect payments contract for coding agents: operations, schemas, validator.
Return the checklist to audit existing ROKI code, ordered by how badly each item fails in production. Use it when reviewing an integration you did not write, or before going live.
| Name | Required | Description | Default |
|---|---|---|---|
| focus | No | Optional area: "webhooks", "security", "payments", "reversals". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds the behavioral detail that the checklist is 'ordered by how badly each item fails in production,' which tells the agent about result prioritization. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler; the purpose and usage are front-loaded. Every word contributes meaning, and the structure is ideal 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?
This is a low-complexity tool with one optional parameter, full schema coverage, and strong annotations covering safety. The description's promise of a checklist is sufficient; no output schema is needed and the context is 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?
The schema provides a complete description for the only parameter 'focus', including allowed values. The tool description does not mention parameters, but with 100% schema coverage the agent already has the needed information, so a baseline 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 uses a specific verb 'Return' and identifies the resource as 'the checklist to audit existing ROKI code', clearly distinguishing it from sibling tools that provide guides, examples, or operations. The phrase 'audit existing ROKI code' precisely defines the tool's scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States explicitly 'Use it when reviewing an integration you did not write, or before going live,' giving clear contextual guidance. It does not mention alternatives or exclusions, but for this simple checklist tool, the likely use cases are fully covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare the payment the API returned against the body you sent, and report anything that does not match. Every other check here looks at what you SEND. This one exists for the errors that survive that: the field name was right and the VALUE was wrong. The API answers 201, warnings comes back empty because there was nothing to warn about, and the merchant charged something else. Catches the amount off by a factor of 100, fee pass-through asked for and returned as zero, tax that was not applied, expires_at already in the past because it was sent as UTC instead of Honduras time, a total that does not add up, and a transaction_id parsed as a number. Run it after every createPayment while you are building, and in your own tests afterwards.
| Name | Required | Description | Default |
|---|---|---|---|
| sent | Yes | The JSON request body you sent to POST /payments. | |
| received | Yes | The payment object the API returned. Paste the response as-is. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate read-only, non-destructive, and idempotent behavior. The description adds extra behavioral context by listing specific error scenarios (e.g., amount off by factor of 100, missing tax, invalid date format) and explaining that the API may return 201 with empty warnings when there are no issues. This goes beyond the annotation hints without contradicting them.
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 overly verbose, with lengthy enumerations of error cases and repetitive phrasing (e.g., multiple clauses about mismatches). It is not front-loaded; while the first sentence states the core action, the subsequent details drag on and could be streamlined. A more concise version would improve clarity and maintainability.
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 covers a wide range of potential mismatches and even mentions a specific HTTP status code (201), but it omits a clear description of the tool's return value or output format. Since there is no output schema, specifying whether it returns a list, a boolean, or a report would be important for completeness. The description is partially complete but leaves this key aspect ambiguous.
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 includes descriptions for both parameters, so coverage is high. The tool description reinforces the meaning by referring to them as 'the body you sent' and 'the payment the API returned,' clarifying the expected roles. It does not add new constraints but provides useful context that ties the parameters to the comparison logic.
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: comparing the payment response against the request body and reporting mismatches. It also distinguishes this check from others by noting that it focuses on the response side, unlike other checks that focus on what is sent.
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 explicit guidance on when to use the tool: 'Run it after every createPayment while you are building, and in your own tests afterwards.' It also differentiates from sibling tools by explaining that other checks look at what you SEND, while this one checks the response for errors that survive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Decide how to integrate ROKI Connect for a given project (web checkout, embedded card fields, mobile app, invoices or recurring billing) and get the constraints that apply before writing code. The modes and the endpoints behind them are read from the corpus, so this answer cannot describe a mode the API no longer has - or miss one it gained.
| Name | Required | Description | Default |
|---|---|---|---|
| context | Yes | What the project is: e.g. "Laravel e-commerce checkout", "iOS app", "card fields on my own page", "invoices from an ERP", "monthly subscriptions". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds valuable context by explaining that modes and endpoints are read from the corpus, ensuring up-to-date information. This goes beyond annotations and clarifies the tool's dynamic nature, but it does not elaborate on output format or potential side effects (which are unlikely given 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 two sentences long, with the purpose in the first sentence and an important behavioral note in the second. There is no fluff or redundant repetition. Every sentence earns its place, and the most critical information (purpose) is 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 the simplicity of the tool (one parameter, no output schema), the description covers essential aspects: what it does, when to use it, and how it stays current. It does not explicitly state the return format, but the phrase 'get the constraints that apply' implies the output content. An explicit mention of return structure would improve completeness, but this is a minor gap, not a fatal flaw.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single 'context' parameter, with a clear description and examples. The tool description repeats some examples (web checkout, mobile app, etc.) but adds no new information beyond the schema. This aligns with the baseline score of 3 for high schema coverage; the description does not compensate for any gaps because there are none.
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: 'Decide how to integrate ROKI Connect for a given project' and lists specific integration modes (web checkout, embedded card fields, mobile app, etc.). It distinguishes itself from sibling tools like roki_search_docs or roki_get_integration_example by focusing on mode selection and constraints, not documentation lookup or code examples.
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 specifies the intended use case: before writing code, for a given project. It enumerates project types, giving clear context for when to invoke the tool. However, it does not explicitly state when not to use it or name alternative tools, so it lacks explicit exclusions but is still clear enough for a competent agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
How authentication works, how the two environments are selected, where credentials come from, and how to store and rotate them safely.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and idempotentHint=true, so the tool's safe, read-only nature is clear. The description adds context about the guide's content but does not disclose return format, pagination, or any other behavioral traits beyond what annotations provide. There is no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the topic and lists the key aspects of the guide. Every element earns its place, with no wasted words or repetition of the tool name.
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?
As a simple, read-only documentation tool with no parameters and no output schema, the description is sufficiently complete. It names the main topics of the guide, which is all an agent needs to decide whether to invoke this tool. It does not explain the return format, but that is unnecessary for a content guide with no structured output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the baseline is 4. The description compensates by explaining what the guide covers (authentication, environments, credentials, storage/rotation), which gives meaningful context without needing to describe parameter syntax or formats.
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 identifies the tool's subject matter—authentication, environment selection, credentials, and safe storage/rotation—which distinguishes it from sibling guides like quickstart or webhook guide. However, it lacks an explicit verb like 'explains' or 'returns', making the action only implied by the tool name and context.
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 explicit guidance is given about when to use this tool versus sibling tools such as roki_get_quickstart or roki_get_webhook_guide. The only usage signal is the subject matter, which is implicit rather than stated. Neither alternatives nor exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the complete text of one section of the integration guide, by number (e.g. "14"), sub-number ("12.1") or title fragment ("webhook").
| Name | Required | Description | Default |
|---|---|---|---|
| ref | Yes | Section number, sub-number, or a fragment of its title. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a safe, read-only, idempotent operation. The description adds meaningful behavioral context about the matching modes (number, sub-number, title fragment) and the guarantee of returning the complete section text, which goes 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 a single, well-structured sentence that front-loads the action and resource, then briefly lists the accepted reference formats. Every word earns its place with no redundancy.
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 simple, read-only tool with one well-documented parameter and no output schema. The description adequately explains the tool's purpose and usage for an agent to invoke it correctly, especially with the supporting annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description essentially repeats the same parameter semantics already in the schema. Baseline 3 is appropriate as the schema does the heavy lifting; the description adds no extra meaning beyond what is structured.
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 ('Return the complete text of one section of the integration guide') and clearly specifies the resource and scope. It distinguishes itself from sibling search tools by emphasizing 'complete text' and the various reference formats.
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 the tool is for retrieving a known section by number, sub-number, or title fragment, giving clear context on when to use it. It does not explicitly name alternatives or exclusions, but the usage context is evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explain an HTTP status or an error message returned by the ROKI API: what it means, the likely cause and what to do. Use this instead of guessing when an integration fails.
| Name | Required | Description | Default |
|---|---|---|---|
| error | Yes | HTTP status ("422"), or a fragment of the message ("Pago no encontrado", "route could not be found", "sandbox"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds context by specifying that the tool provides the meaning, likely cause, and recommended action. This goes beyond what annotations convey, though it does not describe the exact output format or any limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, with the purpose front-loaded and the usage guidance in the second sentence. Every word contributes value; there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, read-only tool with no output schema, the description fully covers what the tool does and when to use it. The sibling context shows no overlapping tool, so the description is complete for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter is fully documented in the schema with examples of HTTP statuses and message fragments. The description restates this concept but does not add new semantic details beyond the schema, fitting the baseline of 3.
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 ('Explain') and a clear resource ('an HTTP status or an error message returned by the ROKI API'). It states exactly what the tool does: explains meaning, likely cause, and what to do. This distinguishes it from all sibling tools, which focus on other aspects like integration, schemas, or validation.
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 says 'Use this instead of guessing when an integration fails,' providing a clear when-to-use context. It does not explicitly name an alternative tool, but no sibling tool offers error explanation, so the guidance is sufficient. Missing a 'when not to use' clause prevents a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a complete, runnable integration example for a stack: configuration, API client, checkout flow, webhook handler with signature verification, and polling fallback.
| Name | Required | Description | Default |
|---|---|---|---|
| stack | No | e.g. "laravel", "php", "node", "express", "python", "fastapi". Omit to list what is available. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable context by enumerating the example contents: configuration, API client, checkout flow, webhook handler with signature verification, and polling fallback. This goes beyond the schema.
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?
Single, front-loaded sentence that names the deliverable and its components without redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only example retrieval tool with one optional parameter and no output schema, the description fully captures what the user gets and how to use it. The 'omit to list' behavior is covered by the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and clearly documents the 'stack' parameter with examples and behavior when omitted. The description does not add parameter-level meaning beyond that, so baseline 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?
Description uses specific verb 'Return' with resource 'complete, runnable integration example' scoped by 'for a stack'. Clearly distinguishes from sibling get_* tools that retrieve docs, schemas, or guides.
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?
Description implies use when you need a runnable example for a given stack, and the schema adds 'Omit to list what is available.' However, it does not explicitly mention when not to use or name alternative tools for other needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full detail for one operation: method, path, headers, request schema field table, responses, and worked examples.
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | operationId (e.g. "createPayment"), or "METHOD /path" (e.g. "POST /payments"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing a safe, read-only profile. The description adds valuable context by disclosing the exact contents of the returned detail: method, path, headers, request schema field table, responses, and worked examples.
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 sentence that front-loads the purpose and uses a colon to introduce the list of included components. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple read-only retrieval tool with one well-defined parameter, no output schema, and rich annotations. The description fully covers what the tool returns and the schema fully covers the input, making the tool sufficiently documented for a capable 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 single parameter 'operation' is fully described in the schema with concrete examples (operationId or METHOD /path). The tool description itself does not add additional parameter semantics, and since schema_description_coverage is 100%, the 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 clearly states the tool retrieves full details of a single API operation, enumerating method, path, headers, request schema field table, responses, and worked examples. It distinguishes itself from sibling tools like roki_list_operations (which lists operations) by focusing on one operation in full.
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 the tool is for when you need comprehensive details of a single operation, as opposed to listing operations. While it does not explicitly name alternatives, the focus on 'one operation' provides clear context for when to use it, and no exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The minimum viable integration sequence, end to end, including the manual portal steps a developer cannot skip.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds valuable context that the output includes manual portal steps a developer cannot skip, which is a behavioral trait beyond the annotations—it tells the agent the guide includes non-automatable actions. This is useful for setting expectations.
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, compact sentence that conveys the core value proposition. It is front-loaded with the key phrase 'minimum viable integration sequence' and adds a crucial caveat about manual steps. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter doc retrieval tool with no output schema, the description explains what the content is (integration sequence) and a key characteristic (manual portal steps). It does not explicitly state the return format, but given the tool's simple nature and the rich sibling context, the description is largely sufficient. However, a phrase like 'returns a guide' would make it fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is trivially complete. The baseline for zero params is 4; the description doesn't need to add parameter semantics. It correctly mentions the integration sequence and portal steps, covering the tool's purpose rather than params, which 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 states the tool provides the minimum viable integration sequence end to end, which implies a quickstart guide. The verb is implicit but the resource is clear: a quickstart. It distinguishes from siblings like roki_get_authentication_guide by focusing on the full sequence rather than a specific aspect, though it doesn't explicitly name 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 implies this is for developers needing a step-by-step integration path, but it provides no explicit 'when to use' vs. alternatives. Given sibling tools like roki_get_doc_section or roki_get_integration_example, a note distinguishing quickstart from deeper docs would improve guidance. The intended use is inferable from the name, but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a fully dereferenced JSON Schema by name (e.g. "PaymentCreateRequest", "Payment", "WebhookEvent"). Use it to know the exact field names, types and constraints.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Schema name. Omit to list all available schemas. |
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 value by explaining 'fully dereferenced' (indicating resolved references) and the optional listing behavior when 'name' is omitted. This goes beyond annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary action, and packed with useful examples and behavioral notes. No filler words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description explains what is returned (a fully dereferenced JSON Schema), how to use it, and when to use it. For a simple lookup tool with one optional parameter, this is 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 coverage is 100% (the 'name' parameter has a description). The tool description enhances this by giving concrete example values (PaymentCreateRequest, Payment, WebhookEvent) and clarifying that omitting the parameter lists all schemas, aligning with the schema's note.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description starts with a specific action ('Return a fully dereferenced JSON Schema'), names the resource ('JSON Schema'), and clarifies the scope ('by name'). Examples of valid schema names make it clear what the tool is for and distinguish it from sibling tools like roki_get_operation or roki_get_doc_section.
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?
States a clear use case: 'Use it to know the exact field names, types and constraints.' This tells the agent when to choose it. It doesn't explicitly list alternatives or exclusions, but given the tool's narrow scope, the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Everything about webhooks: portal registration, event types, payload shape, HMAC signature verification over the raw body, idempotent processing, and the polling fallback.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing a safe read-only operation. The description adds useful context about the guide's coverage, including HMAC verification over the raw body and the polling fallback, without contradicting annotations. However, it does not disclose the exact return format or whether the content is static, so a slight gap remains.
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 sentence with a compact list of topics, making it easy to skim and front-loaded with the primary subject 'webhooks'. The phrase 'Everything' is slightly hyperbolic, but it doesn't add significant clutter. It could be slightly more precise, but overall structure is clean.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter guide tool, the description adequately enumerates the covered topics, giving an agent a clear basis to decide whether to call it. There is no output schema, and the description does not clarify the return format (e.g., a text blob or a link), which introduces minor ambiguity, but it covers the key decision-relevant content.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and an empty input schema, making parameter information irrelevant. The schema description coverage is trivially 100%, and the description correctly omits parameter details. Per the rubric, a baseline of 4 applies when there are no parameters, and nothing here lowers that.
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 identifies this as a guide/reference for webhooks, listing specific topics such as portal registration, event types, payload shape, HMAC signature verification, idempotent processing, and polling fallback. This distinguishes it from sibling tools like roki_verify_webhook_signature, which performs verification rather than documents it. However, the opening phrase 'Everything about webhooks' is broad and lacks a sharp boundary, 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?
The description implies usage when an agent needs webhook information, but it does not explicitly state when to prefer this tool over related alternatives such as roki_verify_webhook_signature or roki_get_doc_section. No exclusions, prerequisites, or when-not-to-use guidance is provided, leaving usage to be inferred rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every operation the API actually exposes, plus the operations that are documented as NOT existing. Call this before writing any integration code so you never invent an endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true; the description adds the valuable detail that it also lists operations documented as NOT existing, which is a beyond-annotations behavioral trait. This gives the agent a clear expectation of the response scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action, no filler. The instruction 'Call this before...' earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema listing tool, the description fully covers purpose, usage, and the unusual inclusion of non-existing operations. Complete as is.
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?
Tool has zero parameters, so baseline is 4. No parameter info is needed; schema coverage is trivially 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'List every operation the API actually exposes, plus the operations that are documented as NOT existing' – a specific verb+resource with clear scope. It also distinguishes from sibling get_operation by framing it as the pre-coding discovery step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs 'Call this before writing any integration code so you never invent an endpoint,' providing a clear when-to-use context. Doesn't name explicit alternatives or when-not-to-use, but the trigger is specific.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Whether the sandbox playground is enabled here, which operations it accepts, its limits, and the sandbox test cards.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing a safe read operation. The description adds context about the specific content returned (enabled status, operations, limits, test cards) without contradicting 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?
A single concise sentence that front-loads the key information. Every phrase adds value, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless informational tool with rich annotations, the description fully covers what the tool reports. No output schema exists, but the description sufficiently sets expectations about the returned information.
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?
There are zero parameters, so the schema already covers everything. The description does not need to add parameter details, and the baseline score of 4 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 resource (sandbox playground) and the specific information it provides: whether it's enabled, accepted operations, limits, and test cards. This distinguishes it from sibling tools like roki_sandbox_try and roki_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when you need sandbox capabilities information) but does not explicitly mention alternatives or exclusions. No direct 'use this instead of X' guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Runs a documented operation against the ROKI sandbox using THIS SERVER'S own test credential, and returns the actual response. Use it to prove an integration works instead of assuming it does - especially after roki_validate_request says a payload is valid.
You never supply a key: this server holds a sandbox-only credential and refuses to run against production. Amounts are capped and links expire quickly, because the sandbox is shared.
| Name | Required | Description | Default |
|---|---|---|---|
| payload | No | Request body for POST operations, or path values such as {"id": 123} / {"transaction_id": "uuid"}. | |
| operation | Yes | operationId to run, e.g. "createPayment", "getPayment", "voidTransaction". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds substantial behavioral context beyond annotations: it uses the server's own test credential, refuses production, caps amounts, and shares links that expire. These are important side-effect details not inferable from the annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the main purpose, then usage context, then safety/limitation notes. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter tool with no output schema, the description explains the operation, the sandbox context, security posture, and typical use case. The return value is simply 'the actual response', which is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both 'operation' and 'payload'. The tool description adds no extra parameter-specific semantics, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'runs a documented operation against the ROKI sandbox' and returns the actual response. It distinguishes itself from sibling tools like roki_validate_request (validation) and roki_get_operation (docs) by focusing on execution against the sandbox.
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?
Explicit guidance is given: 'Use it to prove an integration works instead of assuming it does - especially after roki_validate_request says a payload is valid.' It also clarifies constraints (never supply a key, production refused, shared sandbox), providing clear when-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the full runnable skeleton for a stack: credential storage, API client, checkout flow, webhook handler with signature verification, and the polling fallback. Use it to start an integration instead of assembling one from memory.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | "hosted" (default), "embedded" or "saved-card". | |
| stack | Yes | e.g. "laravel", "node", "express", "python", "fastapi", "php". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context by detailing what the returned skeleton contains, which helps the agent know exactly what to expect. 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 only two sentences, front-loaded with the action verb 'Return,' and lists components efficiently. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only scaffold-generation tool with good annotations and 100% schema coverage, the description is complete. It states what the tool does, what it returns, and when to use it, without needing to over-explain given no output schema is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'stack' and 'mode' described in the input schema. The description does not add extra parameter information, but the schema carries the full burden, so baseline 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 clearly states the tool returns a full runnable skeleton for a stack and enumerates the components (credential storage, API client, checkout flow, webhook handler, polling fallback). It distinguishes itself from siblings by positioning it as the way to start an integration rather than assembling one from memory.
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 with 'Use it to start an integration instead of assembling one from memory.' However, it does not name specific alternative tools (e.g., roki_get_integration_example), so it offers clear context but no formal when-not/exclusion clause.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the official ROKI Connect corpus (integration guide, API operations and schemas) and return ranked excerpts. Use this first when you need any ROKI-specific fact. Never answer a ROKI question from memory or from another payment gateway's conventions.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum results (default 6). | |
| query | Yes | What you need to know, e.g. "webhook signature", "tip fields", "idempotency". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to restate safety. It adds value by specifying the corpus (official ROKI docs) and that results are 'ranked excerpts', which gives useful behavioral context beyond annotations. Minor gap: no mention of result format details or pagination, but the annotations lower the bar.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose and scope, plus direct usage guidance. No wasted words; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward search tool with strong annotations and a fully-described parameter schema, the description sufficiently explains what the tool searches, what it returns, and when to use it. The absence of an output schema is mitigated by the phrase 'ranked excerpts', which sets expectations for the return type.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both query and limit having clear descriptions and examples. The description's 'need any ROKI-specific fact' reinforces query semantics but doesn't add new parameter details beyond what the schema already provides. Baseline 3 is appropriate since the schema carries the semantic load.
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 searches the official ROKI Connect corpus and returns ranked excerpts, using specific verbs and naming the resource scope. It distinguishes itself from sibling tools by framing itself as the go-to for any ROKI-specific fact, which separates it from more targeted getters like roki_get_operation or roki_get_doc_section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use this tool first for any ROKI-specific fact and warns against answering from memory or applying conventions from other gateways. This provides clear when-to-use guidance and implies that other tools may be used after initial discovery, though it doesn't enumerate specific alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Server version, corpus contents and freshness. Safe first call to confirm the connection works. Exposes no credentials and no merchant data.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already declaring read-only, idempotent, and non-destructive hints, the description adds value by specifying the return contents (version, corpus, freshness) and the privacy guarantee of exposing 'no credentials and no merchant data.' This goes beyond the annotations and helps an agent understand what to expect from the call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences each provide distinct value: what the tool reports, when to use it, and safety guarantees. There is no fluff, repetition, or unnecessary detail, and the most important information is front-loaded in the first sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters and no output schema, the description covers all essential aspects: purpose, output contents, usage timing, and safety. It is complete enough for an agent to decide whether and when to invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema is empty. The description appropriately focuses on output semantics rather than parameter explanations, meeting the baseline for a parameterless tool.
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 identifies the tool as a status/health check reporting 'Server version, corpus contents and freshness,' which is a specific verb+resource construction. It distinctly differs from the sibling documentation tools by focusing on connectivity confirmation rather than content lookup.
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 phrase 'Safe first call to confirm the connection works' provides explicit guidance on when to invoke this tool—first, to verify connectivity. The reassurance that it exposes no credentials or merchant data reinforces its suitability as a safe preliminary probe. It doesn't name specific alternatives, but the use case is clear given the tool's nature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate a payload against the official schema WITHOUT sending it, and check the business rules the API enforces. Critical for this API: it ignores unknown fields and returns 201, so a typo produces a misconfigured payment rather than an error. The response names what it dropped in warnings, but by then the payment exists - validating here means it is never created. Always validate before writing or shipping integration code.
| Name | Required | Description | Default |
|---|---|---|---|
| payload | Yes | The JSON request body you intend to send. | |
| operation | Yes | operationId, e.g. "createPayment". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnly and idempotent hints, but the description adds crucial behavioral context: the tool does not send the request, the API silently ignores unknown fields with a 201, and the response includes warnings about dropped fields. This goes well beyond the annotations and explains the real-world consequences.
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 action, then provides critical context about the API's failure mode, and ends with a directive. Every sentence adds significant value, and it is concise enough to be read 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?
Despite no output schema, the description explains the return behavior (warnings about dropped fields) and the consequence of not validating. It covers purpose, usage, behavioral details, and the API quirk, making it complete for a tool with only two parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters ('operationId' and 'the JSON request body you intend to send'). The description adds the 'without sending' context and mentions business rules, but does not elaborate on parameter formats or additional constraints beyond the schema, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool validates a payload against the official schema and checks business rules without sending it. This distinguishes it from siblings like roki_sandbox_try (which would send) and roki_get_schema (which only retrieves schema).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Always validate before writing or shipping integration code' and explains the critical API behavior (ignores unknown fields, returns 201) that makes validation necessary. This provides strong when-to-use guidance and implicitly contrasts with actually sending the request.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check a ROKI-Signature header against the raw body and the signing secret. When it fails, this does not just say "invalid" - it tries the specific wrong constructions developers actually write and tells you which mistake you made. Use it whenever webhook verification rejects real events. On the signing secret: this is ROKI's own server and ROKI issued that secret, so sending it here discloses nothing new. It is used to recompute the HMAC and is never stored, logged or counted.
| Name | Required | Description | Default |
|---|---|---|---|
| raw_body | Yes | The EXACT raw request body as received, byte for byte, before any JSON parsing. | |
| signing_secret | Yes | The signing secret from the portal, for the same environment as the event. Held in memory for the duration of the call only: this server logs no tool arguments. | |
| signature_header | Yes | The full ROKI-Signature header value, e.g. "t=1719234300,v1=8f3c..." |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond that: it explains that on failure it 'tries the specific wrong constructions developers actually write' and provides privacy assurances about the signing secret ('never stored, logged or counted'). This goes beyond the basic annotation hints.
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 well-structured. It opens with the core action, then explains diagnostic behavior, usage context, and a privacy note. Every sentence adds useful information without redundancy or 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 tool's simplicity (3 required params, no output schema) and strong annotations, the description is complete. It covers what, when, and important security context. The output behavior is implied by 'tells you which mistake you made,' so no critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description reinforces the parameter semantics by explaining the purpose of the signing secret and its handling, but does not add significant new meaning beyond the schema's already detailed field 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 states exactly what the tool does: 'Check a ROKI-Signature header against the raw body and the signing secret.' It also distinguishes itself from sibling tools by focusing on webhook signature verification and diagnostic failure analysis, making the purpose clear and 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 explicitly says 'Use it whenever webhook verification rejects real events,' providing clear when-to-use guidance. It doesn't explicitly mention alternatives or when not to use it, but the context is strong enough for an agent to select it appropriately.
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. Dates show when Glama detected each change.
roki_choose_integration_mode1 field changedInput schema / properties / context / descriptionPrevious value: -"What the project is: e.g. \"Laravel e-commerce checkout\", \"iOS app\", \"invoices from an ERP\", \"subscriptions\"."New value: +"What the project is: e.g. \"Laravel e-commerce checkout\", \"iOS app\", \"card fields on my own page\", \"invoices from an ERP\", \"monthly subscriptions\"."roki_check_resultroki_audit_integrationroki_choose_integration_moderoki_get_authentication_guideroki_get_doc_sectionroki_get_errorroki_get_integration_exampleroki_get_operationroki_get_quickstartroki_get_schemaroki_get_webhook_guideroki_list_operationsroki_sandbox_inforoki_sandbox_tryroki_scaffold_integrationroki_search_docsroki_statusroki_validate_requestroki_verify_webhook_signatureClaiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user, then choose Claim with GitHub. An organization namespace such as io.github.acme/server also needs that organization to have installed the Glama AI GitHub App and approved its permissions, because GitHub discloses organization membership only to apps it has installed. Use HTTP or DNS when it has not.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
A paid remote MCP for OpenAI Codex agent coordination MCP, built to return verdicts, receipts, usage
Agent bookkeeping, sanctions, KYB, VAT and e-invoice checks - pay per call in USDC
Pay for APIs with USDC. Read-only x402 payment discovery, verification, evidence, and status.
Add one secure layer between your agents and this server.
Each tool has a clearly distinct purpose, from searching docs to validating requests to verifying webhook signatures. Even similarly named tools like roki_get_integration_example and roki_scaffold_integration are differentiated by 'complete runnable' vs 'skeleton'.
Tools mostly follow a roki_verb_noun pattern (get, list, search, validate, verify), but a few deviate with noun-only names like roki_status and roki_sandbox_info. The prefix and clear verbs make the pattern predictable overall.
18 tools is on the heavy side, but each serves a distinct role in the integration workflow covered by this server. The count is justified given the breadth of documentation, validation, sandbox, and example generation features.
The tool surface covers the full lifecycle of an integration: discovery (search_docs, list_operations), learning (guides, examples, schemas), validation (validate_request), sandbox testing (sandbox_try), verification (verify_webhook_signature), and post-integration auditing. No obvious gaps for the server's stated purpose.
