Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@tiendanube-mcp what OAuth scope do I need to create an order?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Servidor MCP para desarrollar apps e integraciones en Tiendanube y Nuvemshop.
claude mcp add tiendanube -- npx -y @commenteme/tiendanube-mcpRequiere Node >= 18. El cliente ejecuta el servidor con npx, así que no hace falta instalarlo. Para Claude Desktop, Cursor, Windsurf, VS Code y otros clientes, mira Otros clientes.
Related MCP server: SignNow API Helper MCP
Reinicia el cliente y pide lo que necesitas en lenguaje natural. El asistente elige la herramienta:
"Que scope necesita POST /orders/{id}/fulfillment-orders/{id}/tracking-events?"
"Arma el receptor de webhooks para order/paid y app/uninstalled con la verificación de firma"
"Genera el flujo de instalación OAuth del app 1234"
"Que eventos de webhook hay para fulfillment orders?"
"Cómo funcionan los slots del checkout en NubeSDK?"
Para quien escribe apps de partners e integraciones propias: Admin API, OAuth, webhooks, NubeSDK, apps del Admin y temas.
Documentación oficial en vivo: search-docs y read-doc leen las páginas Markdown que nuvemshop.dev publica para agentes, en inglés, portugués o español. Cada respuesta trae la URL de la página.
Índices de la Admin API 2025-03, sin red: 228 endpoints con el scope que piden y su página de referencia, los 18 grupos de scopes OAuth y los 57 eventos de webhook, con los tres de privacidad obligatorios aparte.
Scaffolding: el receptor de webhooks (firma x-linkedstore-hmac-sha256 sobre el body crudo, 200 inmediato y una prueba) y el flujo OAuth (redirección con state y canje del code con body JSON). Las herramientas devuelven los archivos (ruta y contenido) para que el cliente los escriba.
Sin credenciales: no pide token de tienda, no escribe en disco y solo se conecta a nuvemshop.dev y tiendanube.dev.
Funciona con Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, GitHub Copilot, VS Code, Windsurf y cualquier cliente MCP con transporte stdio.
Tiendanube tiene un Admin MCP oficial para operar una tienda conversando: crear productos, ajustar stock y precios, ver pedidos, manejar cupones y promociones. Si lo que necesitas es operar una tienda, ocupa ese. Para quien construye sobre la plataforma no había servidor: este responde que endpoint, que scope y que evento usar, y entrega el código de las partes que todo app repite. Va junto con las skills de tiendanube-skills.
En claude_desktop_config.json (Claude Desktop), ~/.cursor/mcp.json o .cursor/mcp.json (Cursor) y ~/.codeium/windsurf/mcp_config.json (Windsurf):
{
"mcpServers": {
"tiendanube": {
"command": "npx",
"args": ["-y", "@commenteme/tiendanube-mcp"]
}
}
}En VS Code, .vscode/mcp.json:
{
"servers": {
"tiendanube": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@commenteme/tiendanube-mcp"]
}
}
}Codex, con el CLI (queda en ~/.codex/config.toml):
codex mcp add tiendanube -- npx -y @commenteme/tiendanube-mcpO a mano, en ~/.codex/config.toml o en .codex/config.toml del proyecto:
[mcp_servers.tiendanube]
command = "npx"
args = ["-y", "@commenteme/tiendanube-mcp"]Gemini CLI, con el CLI (-s user lo deja en ~/.gemini/settings.json; sin -s, en .gemini/settings.json del proyecto):
gemini mcp add -s user tiendanube npx -y @commenteme/tiendanube-mcpGitHub Copilot CLI, en ~/.copilot/mcp-config.json o en .mcp.json del proyecto, con el mismo JSON de mcpServers de arriba. En VS Code, Copilot usa el .vscode/mcp.json.
Cualquier cliente con transporte stdio sirve: el comando es npx y los argumentos, -y @commenteme/tiendanube-mcp. En Claude Code, --scope project deja la configuración en .mcp.json para compartirla con el equipo.
Herramienta | Que hace | Red |
| Busca en el índice | Sí |
| Lee una página o una sección, por URL o ruta del sitio. Otros dominios se rechazan. | Sí |
| Endpoint por ruta (acepta ids reales, versión y store id), recurso o palabras: URL completa, scope y referencia. | No |
| Los scopes OAuth y los recursos que abren, o el scope de un recurso o una ruta. | No |
| Los eventos de webhook por grupo, con como registrarlos y verificarlos. | No |
| Receptor Express en TypeScript con verificación de firma y una prueba con | No |
| Instalación OAuth en Express: | No |
La documentación de nuvemshop.dev no tiene licencia abierta, así que el paquete no la trae: search-docs y read-doc la leen en vivo y la guardan solo en memoria mientras corre el proceso. Los archivos de data/ son índices de hechos armados por scripts/ingerir.ts desde esas páginas: métodos, rutas, nombres de recursos, de scopes y de eventos, y el enlace a cada página. Ningún texto de la documentación entra en el paquete. Las contradicciones que encontramos en la documentación están en tiendanube-skills/docs/divergencias.md.
git clone https://github.com/commentemeapp/tiendanube-mcp.git
cd tiendanube-mcp
npm ci
npm run checknpm run check es el gate: Prettier, tipos, build, las pruebas (las herramientas de documentación leen páginas sintéticas de test/fixtures/, sin red), probar-mcp, que arranca el servidor por stdio como un cliente, y la búsqueda de rastros. Para probarlo en un cliente:
claude mcp add tiendanube-local -- node /ruta/a/tiendanube-mcp/build/index.jsCorre npm run ingerir: baja las páginas de recursos de la versión 2025-03, el llms.txt, la autenticación y los webhooks, y reescribe data/. Después, npm run check y commitea data/: el paquete lo necesita.
El trabajo nace en una rama salida de dev y el PR va contra dev. Después de probar localmente, dev se promueve a main con merge de la rama completa. El CI corre npm run check en Node 18, 20 y 22.
Para publicar, sube la versión en package.json, server.json y CHANGELOG.md y empuja un tag v*: el workflow publish.yml corre el gate, publica en npm con provenance, crea el GitHub Release y publica server.json en el MCP Registry. Los cambios de cada versión están en CHANGELOG.md.
Abre un PR contra dev, con Conventional Commits y npm run check en verde.
MIT. Lo que el paquete trae y lo que no, en NOTICE.
Hecho por commente.me · hablecon@commente.me
Look up Tiendanube / Nuvemshop Admin API endpoints by path, resource or keywords: method, path, full URL with version and store_id, the OAuth scope it needs and the reference page. Works offline from an index of the 2025-03 reference. Use it when writing or reviewing API calls.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results for keyword search (default 15) | |
| query | Yes | A path ("/orders/{id}/fulfill", "/products/123/variants"), a resource name ("Fulfillment Order") or keywords ("tracking event", "custom fields product") | |
| method | No | HTTP method |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new context beyond that: the results come from an offline index pinned to the 2025-03 reference, which tells the agent about staleness and no-network behavior. It does not mention result limits or no-match behavior, which keeps it below a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the lookup modes and followed by the return fields and the usage cue. Every clause carries information; the return-field list earns its place because there is no output 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?
With no output schema, the description usefully enumerates what comes back (method, path, full URL with version and store_id, OAuth scope, reference page) and notes the offline/versioned index. It leaves open whether matching is exact or fuzzy and what an empty result looks like, which are the remaining gaps for a search 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?
Schema description coverage is 100%, and the schema already spells out the query forms, the method enum, and the limit default/max. The description's "by path, resource or keywords" restates what the query parameter documentation already provides, adding no syntax or behavior beyond it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Look up ... Admin API endpoints") plus the three lookup modes (path, resource, keywords) and the fields returned. The resource type (endpoints) separates it implicitly from siblings like search-docs and lookup-scope, but no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Use it when writing or reviewing API calls" gives a clear triggering context, and the path/resource/keyword enumeration hints at valid input styles. It stops short of stating when to prefer search-docs or lookup-scope instead, so the routing decision is left partly to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the OAuth scopes of Tiendanube / Nuvemshop apps and the resources each one opens, or find the scope for a resource, endpoint path or scope name. Use it when choosing the scopes of an app in the Partners Portal or debugging a 401/403.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | A scope ("write_fulfillment_orders"), a resource ("Draft Order") or a path ("/orders/{id}"). Empty lists every scope. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is fully handled. The description adds only that results describe which resources a scope opens; it says nothing about result size, whether matching is fuzzy or exact, or how resource names map to paths.
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, no filler, with the capability front-loaded and the usage trigger second. Every clause 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 single optional-parameter, read-only lookup with no output schema, the definition covers what is returned at a conceptual level (scopes and the resources they open) and when to reach for it. Only the result shape and matching behavior are underspecified, which is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the query parameter's accepted forms (scope name, resource, endpoint path, empty for all) are fully documented in the schema. The description adds no syntax or matching details beyond that, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: listing OAuth scopes of Tiendanube/Nuvemshop apps and the resources each opens, plus reverse lookup by resource, path or scope name. This is clearly distinguishable from siblings like lookup-endpoint or search-docs.
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 names when to use it: choosing app scopes in the Partners Portal or debugging a 401/403. It does not name an alternative tool or state exclusions, so it falls short of a 5, but the trigger context is concrete enough to route an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the webhook events of Tiendanube / Nuvemshop (orders, products, customers, fulfillment orders, locations, billing, app lifecycle and the required privacy webhooks), or find one, with how to register and verify them. Use it before registering webhooks or writing a receiver.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | An event ("order/paid"), a group ("fulfillment_order") or empty for the full list |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare read-only, idempotent, non-destructive, closed-world behavior. The description adds that the tool includes registration and verification guidance and covers required privacy webhooks, which is useful context beyond the annotations, but it omits return format or pagination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded and the second sentence gives a compact usage instruction. The first sentence is long because of the parenthetical event-family list, but that list earns its place by scoping what the tool covers.
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 lookup with one fully described optional parameter and no output schema, the description covers what is listed, how to narrow it, and when to use it. It does not describe the response shape or pagination, which is a minor gap for 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?
Schema description coverage is 100%, and the single optional query parameter is fully documented with examples like 'order/paid', 'fulfillment_order', and empty for the full list. The description adds no query syntax or selection detail beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List the webhook events of Tiendanube / Nuvemshop' and enumerates the event families covered. It is distinguishable from sibling documentation and scaffold tools by its webhook-event lookup focus, although it does not explicitly name a sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear timing instruction: 'Use it before registering webhooks or writing a receiver.' It lacks when-not guidance and does not point to alternatives such as search-docs or read-doc, so it is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a page of the official docs, or one section of it, by URL or site path. Fetched live as Markdown from nuvemshop.dev or tiendanube.dev; other hosts are refused. Use it after search-docs, lookup-endpoint or when the user pastes a docs link.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Page URL on nuvemshop.dev or tiendanube.dev (with or without .md, an #anchor selects a section), or a site path such as "api/resources/2025-03/order" | |
| locale | No | Docs language: en-US (default), pt-BR (Nuvemshop) or es (Tiendanube) | |
| section | No | Heading or anchor of one section to return instead of the whole page | |
| maxChars | No | Truncate the answer to this many characters (default 20000) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the description's added value is the host allowlist ('nuvemshop.dev or tiendanube.dev; other hosts are refused') and the fact that content is fetched live as Markdown. Those are real behavioral facts not present in the annotations. It does not say what happens on an unknown page or missing section.
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 zero filler: the capability and host constraint come first, the routing guidance second. Nothing is repeated and every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only fetcher with a fully documented 4-parameter schema and no output schema, the description supplies the essentials: return format (Markdown), host restriction and call sequencing. The only gap is failure behavior when a URL, locale or section does not resolve.
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 every parameter already documents its format, enum values, default and char limit, so baseline 3 applies. The description's 'by URL or site path' and 'one section of it' merely restate what the url and section properties already say, adding no new syntax or 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?
States a specific verb and resource ('Read a page of the official docs, or one section of it') plus the two accepted addressing modes (URL or site path). The scope is narrow enough ('docs') and the sibling search-docs is implicitly contrasted with reading, so an agent can distinguish it without opening the 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?
Explicitly sequences usage: invoke after search-docs or lookup-endpoint, or when the user pastes a docs link. That gives clear positive conditions and quietly excludes the search use case. It stops short of an explicit when-not statement (e.g. 'do not use to search or to read non-Nuvemshop hosts beyond the refusal note').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate the Express (TypeScript) OAuth 2 authorization code flow of a Tiendanube / Nuvemshop app: install redirect with state, callback that exchanges the code with a JSON body and stores the token per app and store. Returns the files for the caller to write. For a full app, it points to the official templates.
| Name | Required | Description | Default |
|---|---|---|---|
| dir | No | Folder for the generated files, relative to the project root (default "src") | |
| appId | Yes | App ID (client_id) from the Partners Portal | |
| brand | No | Which domain the merchant sees (default tiendanube); the two token URLs are equivalent |
| Name | Required | Description |
|---|---|---|
| files | Yes | Files to write. The server never writes to disk. |
| notes | Yes | Next steps and caveats |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, and the description usefully confirms the mechanism: it 'Returns the files for the caller to write' rather than writing to disk, which explains why a generation tool is marked non-destructive. It adds the token-storage model (per app and store) and the JSON-body exchange detail, though it omits any credential or rate-limit prerequisites.
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 zero filler, front-loading the framework, language, and flow before the return-and-fallback note. Every clause carries information an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values needn't be explained, and the description covers scope, the file-return contract, and the template fallback. The remaining gap is minor: no statement of what the caller must have configured (credentials) before invoking it.
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 appId, dir, and brand are already documented, including the brand enum and its default. The description adds no parameter-level syntax or format detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and artifact: 'Generate the Express (TypeScript) OAuth 2 authorization code flow' for Tiendanube/Nuvemshop, going so far as to enumerate the install redirect, state handling, and callback exchange. This is far more specific than scaffold-webhook-handler's scope, so an agent can distinguish the two without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context (scaffolding the OAuth install flow) and a fallback pointer: 'For a full app, it points to the official templates,' which implicitly tells the agent this tool is for the OAuth piece only. It stops short of explicitly naming siblings like read-doc or lookup-scope as alternatives for partial needs, so it falls just below the top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate an Express (TypeScript) webhook receiver for Tiendanube / Nuvemshop: x-linkedstore-hmac-sha256 verification over the raw body, immediate 200, one case per event and a node:test for the signature. Returns the files for the caller to write; the server never writes to disk.
| Name | Required | Description | Default |
|---|---|---|---|
| dir | No | Folder for the generated files, relative to the project root (default "src") | |
| events | Yes | Events to handle, as in lookup-webhook-event (e.g. ["order/paid", "app/uninstalled"]) |
| Name | Required | Description |
|---|---|---|
| files | Yes | Files to write. The server never writes to disk. |
| notes | Yes | Next steps and caveats |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true and idempotentHint=true already supplied, the description still adds meaningful behavior: it returns files for the caller to write and explicitly states 'the server never writes to disk', which reconciles the word 'Generate' with the read-only annotation. It also discloses the security-relevant detail of HMAC verification over the raw body and the immediate-200 response contract.
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 front-loaded sentence where each clause carries new information — artifact type, platform, signature scheme, response contract, test generation, and the no-disk-write constraint. No filler or restatement of the title.
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?
An output schema exists, so return values need not be explained, and the description adequately covers the generation contract and the fact that nothing is persisted. The only gap is routing guidance relative to scaffold-oauth-callback and confirmation of whether event names must come from lookup-webhook-event.
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 both parameters (dir, events) are already documented there, including the default for dir and the pointer to lookup-webhook-event. The description adds no additional parameter meaning, 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?
States a specific verb+resource+platform: 'Generate an Express (TypeScript) webhook receiver for Tiendanube / Nuvemshop', then enumerates what the generated artifact contains (HMAC verification, immediate 200, one case per event, node:test). This clearly separates it from search-docs / lookup-* siblings and from scaffold-oauth-callback.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: the agent can infer this is the tool to call when it needs a webhook receiver skeleton. There is no explicit when-to-use/when-not guidance and no mention of the closest alternative, scaffold-oauth-callback, nor a statement that event names should first be resolved via lookup-webhook-event (that hint lives only in the schema).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the official Tiendanube / Nuvemshop developer docs (Admin API, apps, NubeSDK, themes, Storefront API, AI and agents), fetched live from nuvemshop.dev. Returns matching pages with URL and, for the top three, the best matching section. Use it first for any "how do I" question; follow up with read-doc.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 5, max 15) | |
| query | Yes | Keywords to look for in the official Tiendanube / Nuvemshop developer docs (e.g. "webhook signature", "fulfillment order tracking", "NubeSDK checkout slot", "sectionable theme schema") | |
| locale | No | Docs language: en-US (default), pt-BR (Nuvemshop) or es (Tiendanube) | |
| excerpts | No | Also fetch the top 3 pages and quote the best matching section (default true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: docs are fetched live from nuvemshop.dev, results include URLs, and the top three can include the best matching section.
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 tight sentences with no wasted wording. It front-loads the tool's purpose before moving to return behavior and the follow-up workflow.
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 four-parameter, read-only search tool with full schema coverage and no output schema, the description supplies the missing return-shape context, names the live source, and routes the agent to read-doc for follow-up. Nothing essential for selecting or invoking it appears to be 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 input schema already documents query, limit, locale, and excerpts, including defaults and bounds. The description adds no parameter-level meaning beyond what the schema provides, which makes the baseline 3 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 a specific verb and resource: searching the official Tiendanube / Nuvemshop developer docs, fetched live from nuvemshop.dev. It lists the covered doc areas and explicitly names read-doc as the follow-up tool, so an agent can distinguish it from that sibling without opening the 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 gives clear when-to-use guidance: use this first for any 'how do I' question, then follow up with read-doc. It does not explain when to prefer the structured lookup siblings such as lookup-endpoint, lookup-scope, or lookup-webhook-event, so the alternative-routing guidance is not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0lookup-endpointlookup-scopelookup-webhook-eventread-docscaffold-oauth-callbackscaffold-webhook-handlersearch-docsScored across 7 tools
The search-docs/read-doc pair is clearly delineated as a two-step flow, and the three lookup-* tools target distinct reference domains (endpoints, scopes, webhook events). The only soft overlap is that lookup-endpoint also returns the OAuth scope, which brushes against lookup-scope, but descriptions explicitly state when to use each.
All seven names follow a strict kebab-case verb_noun pattern (search-docs, read-doc, lookup-endpoint, lookup-scope, lookup-webhook-event, scaffold-webhook-handler, scaffold-oauth-callback). The lookup-* and scaffold-* families are internally parallel and predictable.
Seven tools is well-scoped for a documentation/reference assistant: two retrieval tools, three reference lookups, and two code generators. Each tool covers a distinct need with no filler.
The surface covers the core developer workflow: find docs, read docs, look up endpoints, scopes and webhook events, and scaffold webhook and OAuth handlers. Minor gaps remain — endpoint lookup is limited to the 2025-03 Admin API (no Storefront API or theme/NubeSDK lookup), and there is no app-boilerplate scaffold beyond the OAuth flow.
Nuvemshop (Tiendanube) e-commerce platform, your store's products, orders, customers, categories and
Search PayU docs, browse the payment integration catalog, and fetch production-ready code.
Provides access to Avalara developer documentation, integration guides, and code examples
Manage Meta apps: creation, configuration, webhooks, permissions, compliance, and App Review.
