> For the complete documentation index, see [llms.txt](https://docs.goassay.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.goassay.ai/developers/reference/mcp-tools.md). # MCP tools Look up the Assay MCP tools, their arguments, returned data and errors. The tools your agent sees depend on sign-in, the connected MCP URL and access policy. Assay provides three discovery and calling tools on the hosted server. Local `assay-mcp` also provides sign-in when disconnected. Tool names below are the MCP names, before any client-added server prefix. A long catalogue name may be listed under a local alias; its description identifies the original Assay name. ## What is listed | Connection state or mode | Tools shown | | ------------------------ | ---------------------------------------------------------------------------------------------- | | Local MCP, signed out | `assay_sign_in`. | | Full discovery | The catalogue tools this URL and agent can access and list. | | Search discovery | Up to five accessible pinned catalogue tools, plus `search_tools`, `get_tool` and `call_tool`. | | Automatic discovery | Chooses full or search based on the URL's threshold and accessible tool count. | The three hosted tools remain callable on scoped URLs even when full discovery does not list them. They cannot expand access beyond that URL and agent. See [URLs and profiles](/developers/use-tools-advanced/urls-and-profiles.md) and [Access policy](/developers/use-tools-advanced/access-policy.md). ## `assay_sign_in` Connect the local MCP to your Assay account. This is a local helper, not a hosted catalogue tool. | Item | Contract | | --------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | Input | Empty object: `{}`. No declared arguments. | | Output | Text with an approval link and instructions to return to the client. First sign-in opens the approval page. | | Existing sign-in | Returns `Assay is connected. Its tools are listed here.` | | Sign-in ended or expired | Returns a terminal login command and, when available, a link you may open. It does not automatically reopen the page. | | Sign-in already running elsewhere | Text tells you to approve it in the other window. | | Failure | Starting sign-in can return a JSON-RPC error for keychain, lock or sign-in setup failure. | | Charge | None. | A link is not proof that approval has completed. Tools appear after sign-in finishes; restart the client if needed. Use [Install assay-mcp](/developers/use-tools-get-started/install-assay-mcp.md) for the approval steps and [Troubleshooting](/developers/use-tools-advanced/troubleshooting.md) for setup failures. ## `search_tools` Find tools by what they do. This is a free read; it does not run a provider call. | Input | Required | Meaning and limits | | ---------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `query` | Unless `cursor` is supplied | String; at most 500 characters and 1,500 UTF-8 bytes after control characters become spaces. An empty string is accepted. | | `category` | No | Category string; lowercased; at most 64 characters. | | `detail` | No | `names`, `summary` (default), or `full`. | | `limit` | No | Integer; default 10 for names, 5 for summary, 3 for full. Above 50 is clamped to 50; below 1 uses the detail default. | | `cursor` | No | The previous response's `nextCursor`. Continues the original query, category, detail and limit. | Extra input properties are refused. With a cursor, the saved search controls paging; other supplied fields do not redefine it. | Output | Meaning | | --------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `results` | Ranked matches. All detail levels include `name` and `score`; `notReviewed: true` can flag an unreviewed provider tool. | | Summary result fields | `summary`, `version`, `kind`, display `price`, structured `assayPrice`, and `freeCallsLeftToday`. | | Full result fields | Summary fields plus `inputSchema`. If too large, `inputSchemaOmitted` and `note` explain how to read it through `get_tool`. | | `categories` | Categories reachable in this discovery response's scoped catalogue. | | `total` | Number of ranked matches, not just this page. | | `nextCursor` | Continuation string or `null`. | | `limitApplied` | Effective requested page size; the byte cap can reduce the actual result count. | Results arrive both as `structuredContent` and JSON text in `content`. The response cap is 256 KiB. Cursors are bound to the credential and canonical URL, expire 10 minutes after the first page and stop after 10 pages. Access is checked again for each page. | Error | Meaning and action | | ------------------------ | -------------------------------------------------------------------------------------------------- | | `TOOL_ARGUMENTS_INVALID` | Wrong argument shape, missing query without a cursor, or exceeded text bounds. Correct the inputs. | | `INVALID_CURSOR` | Expired, changed or mismatched continuation. Start a new search. | | `RATE_LIMITED` | Search limit reached: 30 per fixed UTC minute per agent across URLs. Wait for `retryAfterMs`. | ## `get_tool` Read one tool's full contract and current price. This is also free. | Item | Contract | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Input | Required `name` string. No extra properties. | | Identity and description | `name`, `kind`, `category`, `tags`, `summary`, `description`, and optional `notReviewed`. | | Input and output | `inputSchema`, `outputSchema`, `optionalInputFields`, `optionalOutputFields`, `examples`. | | Version | `version`, optional `changelog`, plus applicable `assay/deprecated` metadata (`sunsetAt` and `replacement`) and provider-tool metadata. It is the version a call through this URL would use. | | Price and supply | `tier`, structured `price` or `null`, `noProviderFits`, `freeCallsLeftToday`, `annotations`. | | Output envelope | `structuredContent` plus JSON text in `content`. | | Charge | None. | | Error | Meaning and action | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | | `TOOL_ARGUMENTS_INVALID` | Missing name, wrong input type or extra properties. Correct the input. | | `TOOL_NOT_IN_TOOLSET` | Not available through this URL and access scope, unknown, or without listable supply. Search again on the intended connection. | | `RATE_LIMITED` | Read limit reached: 120 per fixed UTC minute per agent across URLs. Wait for `retryAfterMs`. | ## `call_tool` Run a tool by name after reading its contract. The call has the selected tool's price; this wrapper adds no separate discovery fee. | Input | Required | Meaning | | ----------- | -------- | --------------------------------------------------------------- | | `name` | Yes | Catalogue tool name. A discovery tool cannot be the inner call. | | `arguments` | No | Object matching that tool's input schema. Defaults to `{}`. | No extra wrapper properties are accepted. Payment and idempotency metadata belong beside `name` and `arguments` in the MCP request's `_meta`, outside the tool arguments. The same metadata is applied to the inner call. | Output | Meaning | | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `content` and `structuredContent` | The selected tool's result, returned unchanged by the wrapper. | | `_meta["assay/receipt"]` | `intentId`, `charged` and `held` amounts with asset and display, `status`, `toolId`, `providerId`, `classification`, `attempts`, and optional `fellBack`. | | `_meta["assay/replayed"]` | `true` on an idempotent replay. Absent on a first answer. | | `isError: true` | Tool or platform refusal. Read the shared error fields below. | A result can arrive with status `VERIFYING` and a held amount. `SETTLED` is the service decision, not confirmation of provider collection. See [Life of a paid call](/developers/under-the-hood/life-of-a-call.md) and [Settlement and the hold window](/developers/under-the-hood/settlement.md). Common errors are `TOOL_ARGUMENTS_INVALID`, `TOOL_NOT_IN_TOOLSET`, `TOOL_NOT_ALLOWED`, `NO_PROVIDER_MATCHES_RULES`, `PAYMENT_REQUIRED` and `PAYMENT_DEBT_OUTSTANDING`. The shared errors below also apply, as do local signing refusals. Use [How paying works](/developers/use-tools-get-started/how-paying-works.md) for setup and [Retries and idempotency](/developers/use-tools-advanced/retries-and-idempotency.md) before repeating an uncertain paid call. ## Catalogue tools called directly Each directly listed tool has its own name, description, `inputSchema` and, when declared, `outputSchema`. Read that descriptor or `get_tool`; there is no fixed argument or result shape for all provider tools. A direct call and the same tool reached through `call_tool` use the same access, payment, idempotency and receipt handling. These tools vary with the catalogue and connection. They are not additional fixed Assay account-management tools. The four named Assay helpers above are the implemented helper set. ## Example These are the `params` objects for MCP `tools/call` requests. This search and read example does not purchase a call. Use the actual name returned by your search for the second request. ```json {"name":"search_tools","arguments":{"query":"weather","detail":"names","limit":3}} ``` ```json {"name":"get_tool","arguments":{"name":"get_weather"}} ``` ## Shared errors and metadata Tool failures normally use `isError: true`, readable text in `content`, and `_meta["assay/error"]`. The error includes `code` and `retryable`; depending on the cause it can also include `message`, `retryAfterMs` or `retryAfter` (seconds), `fixUrl`, `callId`, `intentId` or structured `details`. Payment requirements also appear in `_meta["x402/paymentRequired"]`. | Code or family | Meaning | Next action | | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `MCP_URL_NOT_FOUND` (**No MCP server at this URL**) | The URL is missing or not available to this connection. | Check the path, version and sharing state in [URLs and profiles](/developers/use-tools-advanced/urls-and-profiles.md). | | `MCP_CREDENTIAL_INVALID` | The credential is missing or invalid. | Sign in again for the intended profile. | | `MCP_AUTH_RATE_LIMITED` | Too many failed credential attempts. | Fix the sign-in, then wait before retrying. | | `TOOL_NOT_IN_TOOLSET`, `TOOL_NOT_ALLOWED` | URL scope or access refuses the call. | Use the intended URL and review agent access in [Access policy](/developers/use-tools-advanced/access-policy.md). | | `TOOL_REMOVED`, `CONTRACT_VERSION_RETIRED` | Tool or selected contract version is no longer served. | Read the returned details and rediscover. | | `UNSUPPORTED_INPUT_FIELD` | Required provider support for an optional input is missing. | Read the tool contract and remove the unsupported field if appropriate. | | `NO_PROVIDER_MATCHES_RULES`, `TOOL_NO_ELIGIBLE_BINDING` | No eligible provider remains. | Review rules or choose another tool. | | `TOOL_ALL_BINDINGS_FAILED` | Eligible provider attempts failed. | Inspect the refusal and retry only when appropriate. | | `TOOL_ARGUMENTS_INVALID` | Input does not match the declared schema. | Correct it before retrying. | | `INVALID_CURSOR` (**This search expired. Search again.**) | The search cursor expired, changed or belongs to another URL or connection. | Start a new search. | | `RATE_LIMITED` | Discovery or refused-call limit reached. | Wait for the returned retry interval. | | `PAYMENT_REQUIRED` | This call needs signed payment permission. | Local `assay-mcp` handles signing after approval and guards. | | `PAYMENT_DEBT_OUTSTANDING` | A previously served call is still owed. | Settle it in the Assay app's funding flow. | | `PAYMENT_INSUFFICIENT_FUNDS` | Escrow cannot cover this call. | Add confirmed funds before repeating it. | | `PAYMENT_NO_SETTLEABLE_CHAIN` | The call cannot settle on the customer's current chain. | Read the returned payment details and use a compatible funded connection. | | `MCP_QUOTA_EXCEEDED` | A free allowance is exhausted. | Wait for its reset or use the returned paid option if available. | | `MCP_SPEND_LIMIT_EXCEEDED`, `MCP_POLICY_AGENT_PAUSED`, `MCP_APPROVAL_REQUIRED` | Agent spending policy refuses the call. | Have the owner review its cap, pause or approval threshold. | | `MCP_VELOCITY_LIMIT_EXCEEDED` | A call-rate, spend-rate or duplicate-request rule was hit. | Wait for its recovery interval. Raising local caps does not help. | | `PROVIDER_REQUEST_ERROR` | The endpoint rejected the mapped request. | Correct the input or investigate the mapping. | | `PROVIDER_SYSTEM_ERROR` | Provider or platform execution failed. | Read the returned reason before retrying. | | `PROVIDER_CONTRACT_VIOLATION` | Provider output broke the promised shape. | Read the refund and call details. | | `IDEMPOTENCY_KEY_REUSED` | This key already names a different operation. | Reuse keys only for the same tool and arguments. | | `IDEMPOTENCY_IN_PROGRESS` | An earlier attempt is still running. Nothing was charged for this retry. | Wait `retryAfter` seconds, then retry with the same key. | | `IDEMPOTENCY_ATTEMPT_STALLED`, `IDEMPOTENCY_RESULT_UNAVAILABLE` | The prior attempt stalled or its result cannot be replayed. | Reconcile the existing call before creating another purchase. | | `MCP_IDEMPOTENCY_KEY_INVALID` | Malformed idempotency metadata on a direct server request. | Use a valid key as described in the retry guide. | | `INTERNAL_SERVER_ERROR` | Unexpected server failure. | Keep the same logical-call key if you retry. | | Local payment refusal (**Assay asked for a payment this app refused: …**) | `assay-mcp` declined to sign. | Look up the reason in [Troubleshooting](/developers/use-tools-advanced/troubleshooting.md#payment-refusals). Changing server access does not change local limits. | Payment, quota and spending-policy refusals can carry further domain codes and recovery fields. Follow their returned reason and the [troubleshooting tables](/developers/use-tools-advanced/troubleshooting.md). The refusal limiter allows 60 refused calls per fixed UTC minute per agent before calls are rate-limited. `tools/list` is an MCP method, not a tool; its limit is 60 per minute per credential and URL and it reports a JSON-RPC error (`-32029`) when limited. Authentication and transport failures can also happen outside a tool result. ## Go further * [Access policy](/developers/use-tools-advanced/access-policy.md) * [Retries and idempotency](/developers/use-tools-advanced/retries-and-idempotency.md) * [Smart contracts](/developers/reference/smart-contracts.md) ## Next You have reached the end of the Developers reference. Return to [Developer docs](/developers/readme.md) to choose an integration topic. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.goassay.ai/developers/reference/mcp-tools.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.