Leitura de clientes da loja Nuvemshop. Ações:
list: clientes paginados (params: page, per_page, q, created_at_min, updated_at_min).
get: cliente por id (requer customer_id).
[Flattened action: get]
Bulk support: accepts customer_ids for batched execution.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | ||
| page | No | ||
| account | No | ||
| per_page | No | ||
| customer_id | No | ||
| customer_ids | No | ||
| created_at_min | No | ||
| updated_at_min | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive traits. The description adds some behavioral context (flattened action 'get', bulk support) but does not disclose authentication needs, rate limits, or fallback behavior on missing entities.
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 (three short lines plus bullet) and front-loads the purpose. It uses a structured bullet list for actions. Minor issue: mixed language (Portuguese and English) may reduce clarity for some agents.
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 the main use cases (list, get, bulk) but lacks output format details, error handling, and explicit mention of read-only behavior (though annotations cover it). Missing explanation of the 'account' parameter and response schema for an 8-parameter tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by grouping parameters under actions (list vs get) and noting which are required for each action (e.g., customer_id for get). However, 'account' parameter is unexplained, and 'q' lacks a semantic hint.
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 reads customers from Nuvemshop and outlines two actions (list and get) with their parameters. However, it does not differentiate from the sibling tool 'nuvemshop_customers_list', which likely has a similar purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use list vs get via parameter requirements, and mentions bulk support. However, it lacks explicit guidance on when to prefer this tool over alternatives like 'nuvemshop_customers_list' and does not specify preconditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Many tools have overlapping functionality, especially the get/list pairs for customers, orders, and products which have identical descriptions except for the default action. The multiple order write tools (cancel, close, fulfill, etc.) also share the same underlying description, making it difficult for an agent to select the correct one.
Tool names mix patterns: some use simple <resource> (nuvemshop_categories), others use <resource>_<action> (nuvemshop_customers_get), and others use <resource>_write_<action> (nuvemshop_orders_write_cancel). The get/list split for customers, orders, and products is inconsistent with the categories tool which lacks such a split.
With 24 tools, the server has an excessive number for its scope. Many tools are redundant (e.g., separate get and list tools for each resource, and individual write tools for order status transitions). Consolidating these would reduce the count and improve usability.
The server covers the main e-commerce resources (categories, coupons, customers, orders, products) with read and write operations. However, there are gaps: no ability to create or delete customers, delete products, or delete coupons. The set is workable but not fully comprehensive.