Search products and stores in local physical shops. Find availability, prices, and store locations. Currently focused on hardware stores in Spain.
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Average 4.9/5 across 21 of 21 tools scored.
Each tool targets a distinct resource/action combination: products, inventory, buy requests, stores, stats, and feedback are clearly separated. Even the image tools distinguish between local bytes and public URL fetching. No plausible confusion between tools.
All tool names follow a consistent lowercase snake_case verb_noun pattern (create_product, delete_inventory_item, search_wanted). Minor deviations like mark_for_sale and get_upload_url are still within the same overall style.
With 21 tools, the set falls into the 16-25 heavy range. While most tools are justified across three domains (products, inventory, buy requests), the count feels slightly bloated and edges into borderline territory.
Product and inventory lifecycles are fully covered, but buy requests only support create and search - there is no update, delete, or list-own functionality, creating a dead end for managing wanted ads. Store and feedback tooling is minimal but acceptable for the stated scope.
add_inventory_itemAInspectAdd an item to the caller's personal inventory.
Authenticated. Required OAuth scope: `inventory:write`.
One creation tool covers all lifecycle states — set ``status`` based
on the user's intent: "I bought" → ``owned``, "I want" → ``wanted``,
"I'm selling" → ``for_sale``. Either ``product_id`` (linked to an
existing Partle product) or ``name`` (freeform) must be set.
**Not idempotent** — each call creates a new row.
Args:
name: Freeform name for items not yet linked to a Partle product.
Either ``name`` or ``product_id`` must be set.
product_id: Link to a canonical Partle product.
status: Lifecycle. One of: ``owned``, ``wanted``, ``for_sale``,
``sold``, ``discarded``. Default ``owned``.
quantity: How many. Fractional allowed. Default 1.
notes: Freeform multi-line text — the dumping ground for anything
not modeled as a column: extra URLs, comments, where stored,
condition narrative, purpose, source, history, log entries.
Markdown is fine. **Put extra URLs here, not in another field.**
acquisition_price: What the user paid.
acquisition_currency: Currency of acquisition_price.
purchased_at: ISO date (YYYY-MM-DD) when it was acquired.
asking_price: When status=for_sale, asking price.
asking_currency: Currency of asking_price.
condition: Free string — typical: ``new``, ``like_new``,
``good``, ``fair``, ``poor``.
external_link: **Primary** click-through URL only (source listing,
vendor page, manufacturer page). Exactly one. Additional URLs
go in ``notes`` as markdown links.
external_id: Stable identifier from the source system, used as a
**dedup key**. Per-user unique when set — same external_id
can't appear twice for one user. Format is up to you (e.g.
``aliexpress:1005004714348221``, ``amazon:order/3024.../line/1``,
content hash). Leave null for handwritten items.
project: Tag for grouping (e.g. "kitchen-renovation").
api_key: Optional API key (`pk_*`, generate at /account).
Used when there is no OAuth token, and also when the OAuth
token lacks the required scope — an explicitly passed key
overrides an ambient token that is scoped too narrowly.
An invalid or revoked token still fails regardless.
Returns:
The newly-created inventory row (with embedded `product` if
linked), or ``{"error": ...}`` on auth/validation failure.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| notes | No | ||
| status | No | owned | |
| api_key | No | ||
| project | No | ||
| quantity | No | ||
| condition | No | ||
| product_id | No | ||
| external_id | No | ||
| asking_price | No | ||
| purchased_at | No | ||
| external_link | No | ||
| asking_currency | No | ||
| acquisition_price | No | ||
| acquisition_currency | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral detail beyond annotations: 'Not idempotent — each call creates a new row.' It details required OAuth scope, the api_key override and failure semantics, the per-user unique dedup key for external_id, and the guidance to put extra URLs in notes. This gives the agent a complete picture of side effects and constraints. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured: an overview paragraph, detailed Args section, and Returns section. Every sentence carries operational information—there is no filler. Markdown bolding highlights critical rules (e.g., '**Not idempotent**', '**Put extra URLs here, not in another field.**'). For a 15-parameter tool, this length is justified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (15 params, no output schema, no enums), the description covers all necessary context: purpose, authentication, parameter semantics, idempotency, dedup uniqueness, return value, and error behavior. The Returns section explicitly describes the success and failure formats, making the tool fully comprehensible without an 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?
Schema coverage is 0%, but the description meticulously defines every parameter: defaults, formats, constraints, examples, and cross-field rules. For instance, it explains status values with intent mapping, distinguishes external_link (exactly one primary URL) vs notes (extra URLs), and gives external_id format examples and dedup semantics. This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear and specific action: 'Add an item to the caller's personal inventory.' This distinguishes it from sibling tools like update_inventory_item or delete_inventory_item. It also covers the two creation modes (product_id vs name) and all lifecycle statuses, leaving no ambiguity about what the tool does.
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 strong usage context: it explains that one creation tool covers all lifecycle states, maps user intent to status values, and states the requirement that either product_id or name must be set. It also flags non-idempotency. However, it does not explicitly name alternative tools for other operations (e.g., update_inventory_item for edits), so it lacks the 'when not to use' dimension.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_buy_requestAInspectPost a public buy request — an ad asking suppliers to reach out.
Use when the user wants others to know they're looking to buy
something. **Independent of personal inventory** — inventory is the
user's private workshop tracking; a buy request is a sales-facing
ad on the public demand feed at /wanted.
Authenticated. Required OAuth scope: ``inventory:write``.
**Not idempotent** — each call creates a new public post.
Args:
name: Short scannable headline ("Looking for X"). Required.
description: Plain text long-form — specs, constraints, delivery
preference. The supplier reads this to decide whether they
can fulfil.
quantity: How many units the poster wants. Default 1.
max_price: Optional ceiling per unit.
currency: Currency for max_price (default €).
contact: Free-form contact (email/phone/Telegram/etc.) shown
publicly. Optional. Without it, suppliers can only respond
via whatever channels you separately make available.
reference_url: Link to a sample/datasheet/manufacturer page.
product_id: Link to a canonical Partle product if asking for a
specific known SKU.
api_key: Optional API key (`pk_*`, generate at /account).
Used when there is no OAuth token, and also when the OAuth
token lacks the required scope — an explicitly passed key
overrides an ambient token that is scoped too narrowly.
An invalid or revoked token still fails regardless.
Returns:
The newly-created buy request, or ``{"error": ...}``.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| api_key | No | ||
| contact | No | ||
| currency | No | € | |
| quantity | No | ||
| max_price | No | ||
| product_id | No | ||
| description | No | ||
| reference_url | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond annotations by disclosing authentication requirements ('Required OAuth scope: inventory:write'), non-idempotence ('each call creates a new public post'), and the api_key override behavior. It also explains the public visibility of contact information, giving an agent important real-world consequences of 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?
The description is long but proportionate to the 9-parameter schema. It front-loads the core purpose, uses clear section markers, and every sentence earns its place—auth, idempotence, public exposure, and parameter semantics are all relevant and non-redundant.
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 states the return value ('The newly-created buy request, or {"error": ...}'). Combined with auth details, non-idempotence, parameter semantics, and usage context, an agent has everything needed to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description carries the full burden of documenting all 9 parameters, and it does so effectively. It adds meaningful guidance for name, description, quantity, max_price, currency, contact, reference_url, product_id, and api_key—including nuanced behavior about when the key overrides a scoped OAuth token. One minor inconsistency: name is described as 'Required' while the schema marks it nullable with a default, but the intent is clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Post a public buy request') and immediately distinguishes it from personal inventory ('Independent of personal inventory'), making it clear this is a sales-facing ad for the demand feed. This separates it from sibling tools like add_inventory_item or create_product with no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool ('Use when the user wants others to know they're looking to buy something') and clarifies what it is not for by contrasting with private workshop inventory. It does not name specific sibling alternatives like search_wanted or mark_for_sale, but the context is clear enough that an agent can route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_productACreate a new product listing on Partle.
Authenticated. Prefer **OAuth**: connect once via the consent flow on
claude.ai (or any MCP client that supports OAuth) and the bearer token
is attached automatically — no `api_key` parameter needed. **Fallback**:
pass an `api_key` (prefix `pk_`, generate at /account) for programmatic
or non-OAuth clients.
Required OAuth scope: `products:write`.
Use when the user wants to add an item for sale. For edits to an
existing product, use `update_product` instead.
**Images.** This tool creates text fields only — no image arg. Do
**not** try to pass image bytes through a tool argument; phone-sized
payloads blow past conversation context limits.
The response includes a one-shot ``upload_url`` (signed, ~15 min TTL,
bound to this product and your authenticated user). To attach an
image from your code-execution sandbox, do **one** PUT request — no
auth headers needed, the URL itself carries the credential:
requests.put(result["upload_url"],
data=open("/path/to/photo.jpg", "rb").read(),
headers={"Content-Type": "image/jpeg"})
The bytes flow Python → HTTP body → Partle, never through the
conversation. The URL works once and expires fast.
Alternative if you don't have local bytes but have a public image URL:
call ``upload_product_image(product_id, image_url=...)`` instead.
**Duplicate prevention.** Same user, same product name (case- and
whitespace-insensitive) returns 409 with `existing.id`, `existing.url`,
**and a fresh `upload_url`** for that existing product — so if the
user is just retrying with a photo, you can attach it directly to the
existing listing without having to create or pick anything new. You
can also call `update_product` to change fields. Don't retry blindly.
**Idempotency.** Pass `idempotency_key` (any unique string per logical
create — UUID or hash of the source listing) and a retry after a
network failure returns the original response instead of creating a
duplicate. Reusing a key with a different payload is a 422.
Args:
name: Product name. Required, 1–200 chars.
description: Long-form product description. Optional.
price: Price in whole currency units, **not** cents (e.g. ``15.99``
means €15.99). Max 100000. Omit for "ask the seller".
currency: Currency symbol. Defaults to `€`. Use `$`, `£`, etc.
url: Link to the merchant's product page. Optional but recommended.
store_id: ID of the store this product belongs to. Omit for a
personal listing not tied to any store.
listing_type: ``in_stock`` (default) when the seller has the item
and it can be bought now. ``tentative`` when they do not stock
it and want to measure interest first — such a listing is kept
out of normal search results and instead collects "I need this"
presses. Only use ``tentative`` if the user explicitly said they
are gauging demand; an item that is merely out of stock today is
still ``in_stock``. If the user is looking to *buy* something
nobody sells, use `create_buy_request` instead — that is the
demand side and it is a different tool.
idempotency_key: Optional retry-safety token. Unique per logical
create. Send the same key on retries to get the same response.
api_key: Optional API key (`pk_*`, generate at /account).
Used when there is no OAuth token, and also when the OAuth
token lacks the required scope — an explicitly passed key
overrides an ambient token that is scoped too narrowly.
An invalid or revoked token still fails regardless. Omit when using OAuth.
Returns:
The created product record including its new `id` and canonical
`partle_url`. Share `partle_url` with the user. Returns
``{"error": ...}`` on auth, dedup, or validation failure (dedup
also returns ``{"existing": {"id", "name", "url"}}``).
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | ||
| name | Yes | ||
| price | No | ||
| api_key | No | ||
| currency | No | € | |
| store_id | No | ||
| description | No | ||
| listing_type | No | in_stock | |
| idempotency_key | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint=false) with idempotency support, but the description adds substantial behavioral context: idempotency key mechanics, duplicate prevention with 409 and existing product details, the one-shot upload_url with TTL, authentication requirements (OAuth scope `products:write`), and error response format. No contradictions 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 lengthy but well-structured: purpose first, then auth, usage, image handling, duplicate prevention, idempotency, args list, and return value. Every sentence serves a purpose, and the front-loading of the core purpose is effective. The length is justified by the tool's complexity, but a slightly more concise presentation (e.g., collapsing some image upload details) could improve readability without losing 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?
Given the tool's complexity (9 parameters, no output schema, rich annotations, 20 siblings), the description covers all necessary facets: authentication, scope, error handling (409 dedup, 422 idempotency, auth failures), image upload workflow, duplicate prevention, and return value structure. No gaps remain for an agent to misuse the 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 0%, so the description carries the full burden. It provides a detailed 'Args' section covering all 9 parameters: name constraints (1-200 chars), price format (whole units, not cents, max 100000, omit for 'ask the seller'), currency defaults, listing_type semantics (in_stock vs tentative with precise conditions), idempotency_key usage, and api_key override behavior. This adds significant meaning beyond the schema's type/default annotations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific verb and resource: 'Create a new product listing on Partle.' It distinguishes itself from siblings by explicitly naming `update_product` for edits and `create_buy_request` for demand-side intent, leaving no ambiguity about when to use this tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance ('use when the user wants to add an item for sale'), direct alternatives (`update_product`, `create_buy_request`, `upload_product_image`), and detailed context on authentication (OAuth vs API key with fallback rules). It also explains when to set `listing_type` to `tentative` vs `in_stock` with clear behavioral criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delete_inventory_itemAPermanently delete an inventory row.
Authenticated. Required OAuth scope: `inventory:write`. Caller must
own the item (404 otherwise). Hard delete — no soft-delete.
Args:
item_id: ID of the row to delete.
api_key: Optional API key (`pk_*`, generate at /account).
Used when there is no OAuth token, and also when the OAuth
token lacks the required scope — an explicitly passed key
overrides an ambient token that is scoped too narrowly.
An invalid or revoked token still fails regardless.
Returns:
``{"deleted": true, "id": item_id}`` on success, or
``{"error": ...}`` on auth / not-found.
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | No | ||
| item_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond annotations by disclosing that this is a hard delete (no soft-delete), requiring ownership, and detailing the api_key fallback behavior including how it overrides an ambient token and that invalid tokens still fail. This is rich behavioral context that complements the destructiveHint and idempotentHint annotations without 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 concise yet dense: the core action is front-loaded, and the argument and return sections are clearly structured. Every sentence adds value, covering auth, ownership, parameters, and response format without 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?
There is no output schema, so the description appropriately includes a returns section. It covers the action, auth requirements, ownership condition, parameter semantics, and error responses, making it fully self-contained for an agent to understand the tool's complete behavior.
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 0%, so the description alone explains both parameters. It defines item_id as 'ID of the row to delete' and gives a thorough explanation of api_key, including when it is used, its format (`pk_*`), how it overrides OAuth tokens, and edge cases. This fully compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Permanently delete an inventory row', a precise verb-resource pairing that clearly identifies the action and target. It distinguishes itself from sibling tools like delete_product and delete_product_image by specifying 'inventory row', which is a distinct resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states prerequisites: required OAuth scope `inventory:write`, caller must own the item, and 404 otherwise. It also explains the api_key override behavior, giving context on when an API key is used. However, it does not explicitly name alternative tools or say when not to use this tool, so it misses the 'explicit exclusions/alternatives' bar for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delete_productAPermanently delete a product listing and all its images. Destructive.
Authenticated. OAuth (scope `products:write`) preferred; `api_key` fallback.
Use only when the user explicitly asks to remove a listing they own.
Cannot be undone — there is no soft-delete or trash bin. Idempotent:
deleting a product that no longer exists returns an error, not duplicate
side effects.
Caller must own the product.
Args:
product_id: ID of the product to delete. Get from `get_my_products`.
api_key: Optional API key (`pk_*`, generate at /account).
Used when there is no OAuth token, and also when the OAuth
token lacks the required scope — an explicitly passed key
overrides an ambient token that is scoped too narrowly.
An invalid or revoked token still fails regardless. Omit when using OAuth.
Returns:
``{"deleted": True, "product_id": int}`` on success, or
``{"error": ...}`` on auth/ownership failure.
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | No | ||
| product_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description discloses that the action cannot be undone, there is no soft-delete/trash bin, idempotency semantics, ownership requirements, and detailed auth fallback behavior. This adds significant context beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded, but the api_key explanation is lengthy. However, all details are relevant and serve to prevent misuse, so it remains appropriately sized.
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 explicitly states success and error return formats. It covers auth, ownership, idempotency, parameters, and return values, making it complete for a destructive 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?
Even though schema coverage is 0%, the description fully explains both parameters. product_id is tied to get_my_products, and api_key has a detailed explanation of when to use it, how it overrides narrow-scoped tokens, and when to omit 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?
The description opens with 'Permanently delete a product listing and all its images,' using a specific verb and resource. It clearly distinguishes itself from sibling tools like delete_product_image and delete_inventory_item by emphasizing the entire listing and its images.
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 when-to-use guidance: 'Use only when the user explicitly asks to remove a listing they own.' It also states ownership and auth requirements, making it clear when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delete_product_imageARemove a specific image from a product. Destructive, idempotent.
Authenticated. OAuth (scope `products:write`) preferred; `api_key` fallback.
Use when an image was uploaded by mistake or the merchant updated their
listing. The product itself is preserved — only the image record and its
file are removed. To remove the product entirely use `delete_product`.
Args:
product_id: ID of the product the image belongs to.
image_id: ID of the image to delete. Visible in the `images` array of
`get_product` responses.
api_key: Optional API key (`pk_*`, generate at /account).
Used when there is no OAuth token, and also when the OAuth
token lacks the required scope — an explicitly passed key
overrides an ambient token that is scoped too narrowly.
An invalid or revoked token still fails regardless. Omit when using OAuth.
Returns:
``{"deleted": True, "product_id": int, "image_id": int}`` on success,
or ``{"error": ...}`` on auth/ownership failure.
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | No | ||
| image_id | Yes | ||
| product_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral detail beyond the annotations: 'only the image record and its file are removed' and 'The product itself is preserved' clarifies the side-effect footprint. It also discloses nuanced auth behaviors (e.g., an explicitly passed key overrides a narrowly scoped token; invalid/revoked tokens still fail). 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 organized into clear sections (purpose, auth, use cases, params, returns), ensuring every sentence serves a distinct function. While somewhat long, the auth nuances and parameter explanations justify the length; no 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 destructive nature, auth complexity, and lack of an output schema, the description covers all essential aspects: when to use, side effects, parameter semantics, return format (`{'deleted': True, ...}`) and error behavior. It also references sibling tools for context, making it complete for an 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?
Schema coverage is 0%, but the description thoroughly explains each parameter. `product_id` and `image_id` are defined with relationships (`image_id` is visible in `get_product` responses), and `api_key` receives an extensive explanation of its override/fallback behavior and failure modes. This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Remove a specific image from a product,' a specific verb ('Remove') with a precise resource ('a specific image') and clear scope. It also explicitly differentiates from `delete_product` by stating 'To remove the product entirely use delete_product,' eliminating ambiguity between sibling tools.
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 when an image was uploaded by mistake or the merchant updated their listing' provides concrete trigger conditions. It also names the alternative tool (`delete_product`) and includes authentication guidance (OAuth scope vs `api_key` fallback), making when-to-use and when-not-to-use explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_my_inventoryAList the caller's personal inventory items.
Authenticated. Required OAuth scope: `inventory:read` (or pass an
`api_key` for legacy/programmatic clients).
Use this when the user asks "what do I own?", "what's on my
wishlist?", "what am I selling?", etc. The returned rows include
every status by default; pass `status` to filter.
Args:
status: Filter by lifecycle. One of: ``owned``, ``wanted``,
``for_sale``, ``sold``, ``discarded``. Omit for all.
product_id: Filter to rows linked to a specific Partle product.
project: Exact-match filter on the project tag.
q: Substring search on `name` and `notes` (case-insensitive).
limit: Page size, 1–200. Default 50.
offset: Pagination offset. Default 0.
api_key: Optional API key (`pk_*`, generate at /account).
Used when there is no OAuth token, and also when the OAuth
token lacks the required scope — an explicitly passed key
overrides an ambient token that is scoped too narrowly.
An invalid or revoked token still fails regardless. Omit when using OAuth.
Returns:
``{"items": [...], "count": int}`` where each item carries
status, quantity, name (or linked product), notes, prices, etc.
On auth failure: ``{"error": ...}``.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | ||
| limit | No | ||
| offset | No | ||
| status | No | ||
| api_key | No | ||
| project | No | ||
| product_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: OAuth scope requirements, api_key fallback and override semantics, the nuance that an invalid/revoked token still fails, default status behavior, pagination limits, and the exact return shape including error handling. This goes well beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized with a clear opening line, an auth section, a usage cue, a labeled Args block, and a Returns block. Each sentence serves a distinct purpose—no fluff. The length is justified by the tool's complexity (7 params, auth fallback, output format).
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 7 parameters, no output schema, and auth complexity, the description covers everything needed: authentication/scope fallback, filtering semantics, pagination, return format, and error behavior. An agent can confidently invoke this tool without additional context.
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 has 0% description coverage, so the description must compensate, and it does thoroughly. Every parameter is explained with additional meaning: status enums are listed, q is defined as case-insensitive substring search on name/notes, limit has a 1–200 range, project is an exact-match filter, and api_key's override behavior is fully described. This exceeds what the raw schema would convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List the caller's personal inventory items,' which is a specific verb and resource that clearly distinguishes this from sibling tools like get_my_products or search_products. It also immediately frames the scope as personal inventory, eliminating ambiguity.
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 states when to use the tool with user-phrase examples ('what do I own?', etc.) and explains the default behavior of returning all statuses. It lacks explicit exclusions or named alternatives (e.g., 'use get_my_products for product listings'), but the context is clear enough for an agent to select this tool appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_my_productsAList products created by the authenticated user.
Authenticated. OAuth (scope `products:read`) preferred; `api_key` fallback.
Use when the user asks "what have I listed?" or before bulk operations
like updating prices across multiple of their products. Distinct from
`search_products`, which searches the public catalog without owner
scoping.
Read-only.
Args:
limit: Max results (1–200, default 50).
api_key: Optional API key (`pk_*`, generate at /account).
Used when there is no OAuth token, and also when the OAuth
token lacks the required scope — an explicitly passed key
overrides an ambient token that is scoped too narrowly.
An invalid or revoked token still fails regardless. Omit when using OAuth.
Returns:
A list of products in the same shape as `search_products`. Returns
``[{"error": ...}]`` on auth failure.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| api_key | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description covers authentication requirements (OAuth scope products:read preferred, api_key fallback), api_key override behavior with edge cases, error return format on auth failure, and read-only nature. This goes well beyond the sparse annotations (readOnlyHint, destructiveHint) and gives the agent concrete behavioral 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 well-structured with clear sections for args and returns, front-loading the core purpose. Every sentence adds value: purpose, auth context, usage timing, sibling distinction, param semantics, and error behavior. 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?
Given the tool's auth complexity, the description covers all necessary context: when to use, auth nuances, return shape, and error handling. The output schema exists, but the description still explains the error case, which is critical for reliable agent behavior. It is fully complete for the tool's complexity.
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 fully compensates by explaining both parameters in depth: limit gets a range and default, api_key gets a nuanced explanation of when to use it, how it overrides OAuth, and failure cases. This adds significant meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists products created by the authenticated user, with a specific verb and resource scope. It explicitly distinguishes itself from search_products, which searches the public catalog without owner scoping, removing ambiguity among siblings.
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 when-to-use guidance (e.g., when the user asks what they have listed, before bulk operations) and names the alternative tool (search_products) while explaining the key difference. This gives the agent clear decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_productAGet the full record for a single product by its numeric ID.
Use after `search_products` returns a candidate the user is interested in,
when you need fields not in the search summary (full description, all
images, sold status, expiration). Don't loop `get_product` over many search
results — re-search with tighter filters instead.
Read-only. No authentication.
Args:
product_id: Integer `id` from a `search_products` result, or visible in
a Partle product page URL (`/p/<id>-<slug>`).
Returns:
A single product object with all fields, including the canonical
`partle_url` to share with the user. Returns ``{"error": ...}`` if the
ID does not exist.
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable context: 'No authentication' and the error return behavior for nonexistent IDs. This goes beyond the annotations, though it doesn't disclose rate limits or other edge cases.
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?
Every sentence serves a purpose: purpose statement, usage context, read-only note, parameter documentation, and return behavior. It is well-structured with clear separations (Args/Returns) and 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 simple, single-parameter tool without an output schema, the description covers usage, parameter source, return contents, and error behavior. It also includes the canonical `partle_url` as a useful return element, making the tool complete for the 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?
Schema coverage is 0% — the schema only gives type integer and title 'Product Id'. The description fully compensates by explaining the ID source (`search_products` result or URL pattern), validation (integer), and format, making the parameter's meaning and origin clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific action: 'Get the full record for a single product by its numeric ID.' This verb+resource+scope structure distinguishes it from sibling tools like search_products (which searches) and get_my_products (which lists own products).
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 provided: 'Use after `search_products` returns a candidate' and 'Don't loop `get_product` over many search results — re-search with tighter filters instead.' This states both when to use and when not to use, with an alternative approach named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_statsAGet top-level Partle platform statistics.
Use for size questions ("how big is Partle?", "how many stores does
Partle cover?"). Aggregate counts only — no per-product or per-store
data; use `search_products` / `search_stores` for that.
Read-only. No authentication. Cheap, but rarely changes — long-running
agents should cache the result.
Returns:
``{"total_products": int, "total_stores": int, "description": str}``.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses read-only, no-auth, cheap cost, and that data rarely changes with a caching recommendation, adding context beyond the annotations' readOnlyHint and destructiveHint. 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?
Four concise sentences, front-loaded with the main purpose, followed by usage guidance, behavioral notes, and return format. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers the tool's purpose, usage scope, behavior, and return shape, which is especially important given the absence of an output schema. All essential information 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?
The tool has zero parameters; the schema is empty and schema_description_coverage is 100%. The description adds no parameter details but none are needed. Baseline for 0 params is 4.
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 ('Get') and resource ('top-level Partle platform statistics'), and explicitly contrasts with `search_products`/`search_stores` for granular data, distinguishing it from siblings.
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 states exactly when to use ('Use for size questions') and when not to ('Aggregate counts only — no per-product or per-store data'), naming alternative tools `search_products` / `search_stores`.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_storeAGet the full record for a single store by its numeric ID.
Use after `search_stores` to retrieve fields not in the search summary
(full address, owner profile, contact details). For a list of *products*
in that store, call `search_products(store_id=…)` instead — this tool
returns store metadata only.
Read-only. No authentication.
Args:
store_id: Integer `id` from a `search_stores` result.
Returns:
A single store object with all fields. Returns ``{"error": ...}`` if
the ID does not exist.
| Name | Required | Description | Default |
|---|---|---|---|
| store_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Read-only' and adds 'No authentication.' It also discloses the error shape for a non-existent ID and clarifies the tool returns store metadata only, going beyond the 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 compact with clear sections (purpose/usage/args/returns) and no filler. Each sentence serves a distinct function, and the formatting makes it scannable.
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 a single-ID lookup and the absence of an output schema, the description covers everything: what it returns, how to invoke it, when to prefer another tool, and the error condition. No gaps remain.
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 only shows store_id as integer, but the description provides the essential source and meaning: 'Integer id from a search_stores result.' This fully compensates for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get the full record for a single store by its numeric ID,' clearly stating the verb, resource, and scope. It also differentiates from sibling tools by explicitly referencing search_stores and search_products.
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 explicit when-to-use guidance ('Use after search_stores to retrieve fields not in the search summary') and redirects to a specific alternative ('call search_products(store_id=…) instead'), making the boundary with siblings unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_upload_urlAMint a one-shot signed upload URL for a product you own.
Authenticated. OAuth (scope `products:write`) preferred; `api_key` fallback.
Use this when you have **local image bytes** (a file the user attached,
bytes you generated/downloaded in your sandbox) and you want to attach
them to a product that already exists. Common cases:
- `create_product` returned 409 (duplicate name) — the listing already
exists; this tool gives you an upload URL for it without creating
anything new.
- You're adding a 2nd, 3rd, … photo to a product.
The returned URL is valid for ~15 min, single product, signed with
your authenticated identity. From your sandbox, do **one PUT**:
requests.put(result["upload_url"],
data=open("/path/to/photo.jpg", "rb").read(),
headers={"Content-Type": "image/jpeg"})
No auth header on that PUT — the URL is the credential.
If you have a public URL (not local bytes), use
`upload_product_image(product_id, image_url=...)` instead.
Args:
product_id: Product to attach the future image to. You must own it.
api_key: Optional API key (`pk_*`, generate at /account).
Used when there is no OAuth token, and also when the OAuth
token lacks the required scope — an explicitly passed key
overrides an ambient token that is scoped too narrowly.
An invalid or revoked token still fails regardless. Omit when using OAuth.
Returns:
``{"upload_url": str, "upload_expires_in": int}``, or
``{"error": ...}`` on auth/ownership failure.
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | No | ||
| product_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses auth requirements ('OAuth (scope products:write) preferred; api_key fallback'), URL validity (~15 min), one-shot nature, and the fact that no auth header is needed on the PUT because the URL is the credential. It also explains api_key override semantics and error behavior, going well beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Though lengthy, it front-loads the main purpose in the first sentence and then organizes into use cases, PUT instructions, args, and returns. Each section adds necessary information; the code snippet is a concrete example.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description includes the return format (`{upload_url, upload_expires_in}` and error case). It covers auth, use cases, and exact HTTP call, making it complete for a 2-param 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?
With 0% schema description coverage, the description fully compensates: product_id is defined as the product to attach to and 'You must own it.' api_key is explained in detail, including when to use it (no OAuth token or missing scope) and override behavior.
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 it 'Mint[s] a one-shot signed upload URL for a product you own' – a specific verb and resource. The description clearly distinguishes it from sibling `upload_product_image` by scoping to local bytes vs public URL.
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 says 'Use this when you have local image bytes' and gives common cases (409 from create_product, adding additional photos). It names the alternative: 'If you have a public URL (not local bytes), use upload_product_image(...)'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
mark_for_saleAMove an inventory item to status=for_sale and set listing fields.
Convenience wrapper over `update_inventory_item` that matches a
natural user request ("list my drill for sale at 30€"). Sets all
three columns (`status`, `asking_price`, `asking_currency`, and
optionally `condition`) atomically.
Authenticated. Required OAuth scope: `inventory:write`. Caller must
own the item.
Args:
item_id: ID of the inventory row.
asking_price: How much you're asking for it. Whole units, not
cents. Required.
asking_currency: Currency. Default `€`.
condition: Free string describing the item's condition (e.g.
``like_new``, ``good``). Optional.
api_key: Optional API key (`pk_*`, generate at /account).
Used when there is no OAuth token, and also when the OAuth
token lacks the required scope — an explicitly passed key
overrides an ambient token that is scoped too narrowly.
An invalid or revoked token still fails regardless.
Returns:
The updated inventory row, or ``{"error": ...}``.
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | No | ||
| item_id | Yes | ||
| condition | No | ||
| asking_price | Yes | ||
| asking_currency | No | € |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description reveals atomicity of updates, OAuth requirements, ownership prerequisite, and the api_key override semantics. It also explains that an invalid token fails regardless, adding important behavioral nuance that annotations do not cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Though detailed, the description is well-organized into purpose, authentication, args, and returns. Every sentence contributes necessary information—no fluff. The length is appropriate for a tool with five parameters and multiple auth scenarios.
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 all key aspects: what the tool does, its relationship to siblings, authentication, ownership, parameter semantics, and return value. It is complete enough to invoke without external docs, especially given 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?
Schema description coverage is 0%, but the description compensates fully by explaining each parameter in detail, including examples, units, and defaults. For instance, it notes asking_price is in whole units not cents, and asking_currency defaults to €. This adds essential meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Move an inventory item to status=for_sale and set listing fields.' It uses a specific verb and resource, and further distinguishes itself by noting it's a 'Convenience wrapper over update_inventory_item' that matches a natural user request, setting it apart from sibling tools like mark_sold.
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 frames this tool as a convenience wrapper for update_inventory_item, telling the user when to prefer it (for natural listing requests). It also provides critical usage context: required OAuth scope, caller must own the item, and behavior of api_key when OAuth is insufficient. This gives clear guidance on when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
mark_soldAMark an inventory item as sold (status=sold).
Convenience wrapper over `update_inventory_item` for the natural
"I sold the drill" request.
Authenticated. Required OAuth scope: `inventory:write`. Caller must
own the item.
Args:
item_id: ID of the inventory row.
api_key: Optional API key (`pk_*`, generate at /account).
Used when there is no OAuth token, and also when the OAuth
token lacks the required scope — an explicitly passed key
overrides an ambient token that is scoped too narrowly.
An invalid or revoked token still fails regardless.
Returns:
The updated inventory row, or ``{"error": ...}``.
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | No | ||
| item_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description discloses authentication requirements, required OAuth scope, ownership condition, the api_key override behavior, and the invalid-token failure mode. It also notes the return type, providing substantial safety-relevant context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clear sections for args and returns. Each sentence adds meaningful information—purpose, wrapper role, auth, parameter details, and output—without unnecessary 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?
For a two-parameter tool with no output schema, the description is fully self-contained: it explains purpose, usage context, authentication, ownership, parameter semantics, and return value. There are no obvious gaps given the tool's simplicity.
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?
Despite zero schema description coverage, the description fully explains both parameters: 'item_id' as the inventory row ID, and 'api_key' with its purpose, override behavior, and failure conditions. This compensates completely for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Mark an inventory item as sold (status=sold).' It differentiates from siblings like 'mark_for_sale' and 'update_inventory_item' by framing itself as a convenience wrapper for the natural 'I sold the drill' request.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates when to use the tool: for natural-language 'sold' requests, and references 'update_inventory_item' as the underlying alternative. However, it does not explicitly state when NOT to use it or list other alternatives, so it falls short of a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_productsASearch Partle's product catalog by name or description.
CRITICAL SEARCH INSTRUCTION: Reason from the job to the product class first,
then search with a descriptive product phrase (e.g. including substrate, material,
or size class). DO NOT blindly search using the user's raw conversational words.
Transform questions like 'what do I need to attach a mirror to a brick wall?'
into a product phrase like 'heavy duty masonry wall anchor'.
Two distinct modes:
- **Default (no flags)** — fast keyword search. ~100ms. Acts like a normal
"dumb" search box: matches the literal words you typed against product
names and descriptions, with stemming. Good for queries where the user
knows the product's likely name ("BC547", "Arduino Uno", "Bosch
drill"). Returns noisy/wrong results on cross-language or attribute
queries ("compost bin" matches Spanish "composta", not real composters).
- **`super_search=True`** — slow, high-quality. ~1–2s. Run when the user
describes what they want rather than naming it: cross-language
("Schraubenzieher Set" → real screwdriver sets even without German
catalog entries), attribute-style ("small metal part with a flat
head"), or any case where the default returns junk. Embeds the query
with voyage-3-large, takes the cosine top-50 over the corpus (with an
exact-name precision boost for part numbers), then a cross-encoder
reranks them.
The two modes are mutually exclusive in practice — pick one based on
whether the user knows the product's name or is describing it.
Use this when the user asks to find a specific product or browse products
matching a query. Prefer over `search_stores` when the intent is product-led
("find a drill") rather than store-led. Use `get_product` afterwards if the
user wants full details for one specific result.
Read-only. No authentication. Rate-limited to 100 requests/hour per IP.
Args:
query: Free-text search term. In default mode, treated as keywords
(each word matched against product text). In `super_search=True`,
treated as a natural-language description.
min_price: Lower bound on price in EUR. Omit for no lower bound.
Null-priced rows are NOT excluded by this filter — pass
`has_price=True` if you need only priced listings.
max_price: Upper bound on price in EUR. Omit for no upper bound.
Tip — narrow by budget: `min_price=10, max_price=50,
sort_by="price_asc", has_price=True`. Products without a listed
price (a large fraction of the scraped catalog) sort last under
either price ordering and are kept in results unless `has_price`
filters them out.
tags: Comma-separated tag filter (e.g. "electronics,bluetooth"). Tags
are AND-ed together.
store_id: Restrict results to a single store. Use the integer `id` from
`search_stores` results.
sort_by: One of `price_asc`, `price_desc`, `name_asc`, `newest`,
`oldest`. Omit to use the default search-relevance ranking.
has_price: When True, exclude products without a listed price (~most
of the scraped catalog). Use this for competitive pricing or
budget-bounded shopping. When False, return only null-priced
listings (rarely useful). Omit to include both.
semantic: Legacy flag. Pure vector ordering, ~250ms. Mostly
superseded by `super_search=True` (which uses the same vector
retrieval plus a cross-encoder rerank for materially better
ordering at the cost of another ~700ms). Keep using it only if
you specifically want vector retrieval *without* the rerank.
super_search: **Enable for natural-language / "describe what I
want" queries.** ~1–2s. Embeds the query with voyage-3-large,
takes the cosine top-50 (with a precision boost for exact-name
matches like part numbers / SKUs), then a cross-encoder reranks
them. Use whenever the user is describing rather than naming —
cross-language ("Schraubenzieher Set"), attribute-style
("small black metal bracket"), or any case where the default
keyword path returns junk. Don't combine with cheap
browse-style queries where the user typed an exact product
name — keyword default is faster there.
On `relevance_score` here: better than the bi-encoder cosine,
but still not a "did I find what the user wanted" gauge.
Behavior to expect: gibberish or fully-off-topic queries cap
around 0.35; loosely-related catalogue clusters can score 0.7+
even when no item truly matches (a "ceramic vase" query in a
catalog with no vases but many ceramic flowerpots will still
score high). **Read the product names** before claiming a
match. The score is most useful as a relative signal within
one result set — a sharp drop between rank N and N+1 marks
where the catalog stops being useful for this query.
limit: Max results (1–100, default 20). Larger limits are slower and
consume rate budget faster.
offset: Skip this many results before returning. Use for pagination
(offset += limit on each follow-up call).
Returns:
A list of products. Each includes `id`, `name`, `price`, `currency`,
`url`, `description`, `store` (id/name/address), `tags`, `images`, a
canonical `partle_url`, and `relevance_score` (cosine similarity 0–1
between the query and the product's embedding when a query was
provided; `None` otherwise). **Always share `partle_url` with the
user so they can view the listing.**
Caveat on `relevance_score`: it is monotonic *within a single search
result set* (useful for spotting a big drop-off between rank 3 and
rank 4), but its absolute value is not well-calibrated across
queries — most results land in 0.55–0.80 regardless of whether the
catalog has truly relevant items. Don't infer "this is a great
match" from a 0.75 score alone.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| limit | No | ||
| query | Yes | ||
| offset | No | ||
| sort_by | No | ||
| semantic | No | ||
| store_id | No | ||
| has_price | No | ||
| max_price | No | ||
| min_price | No | ||
| super_search | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say readOnlyHint=true and destructiveHint=false, which the description confirms with 'Read-only. No authentication.' Beyond that, it discloses rate limits (100/hour per IP), the behavior of null-priced products sorting last unless has_price is set, the inner workings of super_search (embedding, top-50, cross-encoder rerank), and extensive caveats about relevance_score calibration. This is far more than annotations provide, adding real behavioral insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but densely informative. The structure is logical: overview, critical instruction, mode comparison, 'use this when', read-only note, Args, Returns. However, super_search behavior is described twice—once in the 'Two distinct modes' section and again in the parameter details—which is redundant. Still, the front-loaded critical instruction and scannable sections earn high marks; the small redundancy costs one point.
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 11 parameters, an output schema, and 20 sibling tools, this description covers every aspect: what results look like, what fields are returned, the caveat on relevance_score, rate limits, mode selection, and sibling differentiation. It even explains how to paginate (offset += limit). There is no missing information the agent would need to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description carries full load for 11 parameters. It goes beyond type/default by explaining real semantics: min_price does not exclude null-priced rows, tags are AND-ed, sort_by affects null-price ordering, semantic vs super_search distinction, and how limit/offset interact. The parameter explanations also include practical tips (e.g., 'min_price=10, max_price=50, sort_by="price_asc", has_price=True'). This is exemplary parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb + resource: 'Search Partle's product catalog by name or description.' It also explicitly distinguishes from sibling tools, stating 'Prefer over search_stores when the intent is product-led' and mentioning 'Use get_product afterwards if the user wants full details for one specific result.' This is exactly what the top tier looks like.
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 extensive when-to-use guidance, including a 'CRITICAL SEARCH INSTRUCTION' on how to transform user questions into product phrases, and a detailed split between default keyword mode and super_search mode with concrete examples (e.g., 'Schraubenzieher Set' → cross-language). It also gives explicit alternatives: use search_stores for store-led intent, and get_product for single-result details. This is a textbook example of usage guidelines.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_storesASearch or list stores in the Partle marketplace.
Use for store-led questions ("what hardware shops are in Madrid?") rather
than product-led ones (use `search_products` for that). Pass no query to
browse the whole catalog.
Read-only. No authentication. Rate-limited to 100 requests/hour per IP.
Args:
query: Free-text search over store name and address. Omit to list
all stores in default order.
limit: Max results (1–50, default 20).
Returns:
A list of stores with `id`, `name`, `address`, `lat`/`lon` (when
geocoded), `homepage`, `type`, and `product_count` (active listings
in the store — useful for competitive-landscape sizing without a
separate `search_products` round-trip). Pass `id` to
`search_products(store_id=…)` to filter the product catalog by that
store.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description adds critical operational details: 'Read-only. No authentication. Rate-limited to 100 requests/hour per IP.' It also discloses data nuances like 'lat/lon (when geocoded)' and the utility of product_count. These are genuine behavioral traits not captured by structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (intro, usage guidance, behavioral notes, Args, Returns). Every sentence serves a purpose, avoiding fluff. It is detailed yet concise, fitting the multi-faceted nature of the tool without being bloated.
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 all necessary aspects: purpose, when to use (vs search_products), parameter semantics, return fields (including optional geocoding), rate limits, and even an integration hint (pass id to search_products). Despite having an output schema, the description enriches it with use-case guidance, making it complete for an AI 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?
With schema description coverage at 0%, the description fully compensates. It explains that `query` is free-text over store name and address, and that omitting it lists all stores in default order. It also clarifies that `limit` accepts 1–50 with a default of 20, adding range and meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Search or list stores in the Partle marketplace', using a specific verb and resource. It clearly distinguishes itself from product-led search by pointing to `search_products` for that use case, which separates it from sibling tools.
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 states when to use this tool: 'Use for store-led questions... rather than product-led ones (use `search_products` for that)'. It also explains how to browse the full catalog by omitting the query, and provides meaningful context about rate limiting and read-only behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_wantedABrowse public buy requests — what users are looking to buy but haven't found through normal supply.
The demand side of Partle. Use this when an agent wants to **offer
matches** (cross-reference open requests against `search_products`
and surface hits) or just survey unmet demand. Every result is a
public posting — users put these up specifically so suppliers can
reach them.
Buy requests are independent of personal inventory (which is private):
these are sales-facing ads, not workshop tracking notes.
Read-only. No authentication. Rate-limited 100 req/hour per IP.
Args:
query: Free-text filter over name + description (case-insensitive
substring). Omit to list everything, newest first.
limit: Max results (1–100, default 20).
offset: Pagination offset.
Returns:
A list of open buy requests. Each includes ``id``, ``name`` (plus a
deprecated ``title`` mirror of it),
``description`` (markdown — read the full text for specs and
constraints), ``quantity``, ``max_price`` + ``currency`` (if the
poster set a ceiling), ``contact`` (if they left an
email/phone/handle), ``reference_url`` (sample or datasheet link
if any), ``posted_by`` (display name), and ``created_at``.
If the poster left a ``contact`` value, that's how a supplier
should respond — Partle doesn't broker the conversation.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses rate limiting (100 req/hour), no authentication, public visibility, and that Partle doesn't broker contact. It also explains response semantics like deprecated title and markdown descriptions, adding significant value.
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 somewhat long but well-structured with intro, usage guidance, Args, and Returns sections. Every sentence adds value, but it could be tightened slightly; the length is justified by the complexity.
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?
Covers all essential context: use case, public/private distinction, read-only and auth, rate limit, parameters, full return fields, markdown behavior, and how to respond. Highly complete for a read-only 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 0%, but the description fully documents each parameter: query as case-insensitive substring filter with omit behavior, limit with range and default, offset for pagination. This fully compensates for the schema gaps.
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 browses public buy requests, the demand side of Partle, differentiating from product search (supply side). It names the exact resource and scope, explicitly distinguishing from sibling tools like search_products and create_buy_request.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: use when offering matches by cross-referencing with search_products, or surveying unmet demand. It also notes buy requests are public sales-facing ads, unlike private inventory. However, it doesn't explicitly state exclusions (when not to use) beyond the implied demand/supply split, so not a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
submit_feedbackAInspectReport a problem with the Partle marketplace API/MCP itself.
Authenticated. Prefer **OAuth**: connect once via the consent flow and the
bearer token is attached automatically. **Fallback**: pass an `api_key`
(prefix `pk_`, generate at /account). Required OAuth scope: `feedback:write`.
Feedback is attributed to your account so reports are trustworthy and the
channel can't be flooded anonymously.
Scope — what this is for:
- A Partle tool description is unclear or its parameters are surprising.
- A Partle response is broken, malformed, or missing fields.
- The Partle catalog is missing a category of products you'd expect.
- Search relevance is off for a specific class of queries on Partle.
Scope — what this is **NOT** for:
- General complaints about tasks Partle isn't designed to do (Partle is
a local-marketplace search/listing API — not a news API, an HTML
hosting service, a portfolio-rebalancing app, a stock brokerage, or
a generic dashboard SaaS).
- Venting that an invented API key was rejected (Partle keys must be
`pk_<hex>`; generate one at /account — don't fabricate them).
- Asking the maintainers to do work the user requested but you can't
do. If you can't fulfil a user request, tell the user — don't submit
feedback about it here.
Don't loop — each call adds a row and pages the maintainer. Resubmitting
the same text within 24h is de-duplicated (returns the existing id).
Args:
feedback: Freeform text up to 5000 characters. Be specific — name
the tool, the input that was confusing, and what you expected.
api_key: Optional API key (`pk_*`, generate at /account).
Used when there is no OAuth token, and also when the OAuth
token lacks the required scope — an explicitly passed key
overrides an ambient token that is scoped too narrowly.
An invalid or revoked token still fails regardless. Omit when using OAuth.
Returns:
``{"id": int, "message": "Thanks for the feedback!"}`` on success, or
``{"error": ...}`` on auth, rate-limit, or validation failure.
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | No | ||
| feedback | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations only providing safety hints (readOnlyHint=false, destructiveHint=false), the description enriches behavioral understanding substantially. It explains authentication requirements (OAuth scope, api_key fallback), attribution to the user's account, deduplication within 24h, and the side effect that each call adds a row and pages the maintainer. This goes far beyond structured annotations and aligns with 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 longer than average but well-structured with clear headings, bullet lists, and a logical flow from purpose to auth to scope to arguments. Every sentence has a purpose, though some examples in the 'not for' list could be trimmed without losing meaning. The front-loading of the core purpose is excellent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is comprehensive for a low-complexity tool with 2 parameters and no output schema. It covers the exact return format, authentication paths, error behavior, scoping rules, and deduplication. There is no missing information an agent would need to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema offers no descriptions for parameters, so the description fully compensates. It explains 'feedback' is freeform text up to 5000 characters and advises specificity. For 'api_key', it clarifies when to use it, how it overrides an OAuth token, and that invalid keys still fail. This adds meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear statement: 'Report a problem with the Partle marketplace API/MCP itself.' This identifies the exact verb (report) and resource (Partle API/MCP), and the scope section explicitly differentiates it from sibling tools by listing what it is and is not for, making it unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Scope — what this is for' and 'Scope — what this is NOT for' sections, giving concrete use cases and exclusions. It also warns against common misuse (e.g., submitting feedback for user requests that can't be fulfilled) and advises alternatives ('tell the user — don't submit feedback about it here'). This is exemplary usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
update_inventory_itemAPatch an existing inventory item. Only provided fields change.
Authenticated. Required OAuth scope: `inventory:write`. Caller must
own the item (404 otherwise — we don't leak existence).
Idempotent: calling twice with the same input yields the same final
state. For lifecycle convenience, see `mark_for_sale` and
`mark_sold` which set the right combination of fields atomically.
Args:
item_id: ID of the inventory row to update. Get from
`get_my_inventory` or `add_inventory_item`'s return value.
(every other param matches `add_inventory_item`; omit any field
you don't want changed.)
api_key: Optional API key (`pk_*`, generate at /account).
Used when there is no OAuth token, and also when the OAuth
token lacks the required scope — an explicitly passed key
overrides an ambient token that is scoped too narrowly.
An invalid or revoked token still fails regardless.
Returns:
The updated inventory row, or ``{"error": ...}`` on auth /
not-found / validation failure.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| notes | No | ||
| status | No | ||
| api_key | No | ||
| item_id | Yes | ||
| project | No | ||
| quantity | No | ||
| condition | No | ||
| product_id | No | ||
| external_id | No | ||
| asking_price | No | ||
| purchased_at | No | ||
| external_link | No | ||
| asking_currency | No | ||
| acquisition_price | No | ||
| acquisition_currency | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (idempotentHint, readOnlyHint false), it discloses the required OAuth scope, owner-only access with 404 to avoid leaking existence, idempotency, API key override precedence, and the error return format. This is substantial added behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized: purpose first, then auth, idempotency, alternatives, arguments, and return value. Every sentence adds important detail; 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 16-parameter tool with no output schema, the description covers auth, ownership, idempotency, patch behavior, alternative tools, and return shape. It gives an agent sufficient context to invoke the tool correctly, including failure modes.
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?
It explains item_id (where to get it) and api_key (when to use, precedence over OAuth) in detail, and clarifies the crucial patch rule: omit any field to leave it unchanged. The remaining 14 params are deferred to add_inventory_item, which is a useful cross-reference but leaves their semantics to another 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 opens with 'Patch an existing inventory item. Only provided fields change,' which uses a specific verb, resource, and clear partial-update semantics. It distinguishes itself from siblings like add_inventory_item and the lifecycle helpers mark_for_sale/mark_sold.
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 directs users to mark_for_sale and mark_sold for lifecycle changes, says when this tool is appropriate for arbitrary field updates, and clarifies auth/ownership requirements. This is clear contextual guidance with named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
update_productAUpdate an existing product listing. Only provided fields are changed.
Authenticated. OAuth (scope `products:write`) preferred; `api_key` accepted
as fallback.
Only fields you pass are changed; omitted fields are preserved.
Idempotent — calling twice with the same input yields the same final
state. For creating a new listing, use `create_product` instead.
Caller must own the product. Trying to update someone else's product
returns an error.
Args:
product_id: ID of the product to update. Get from `create_product`'s
return value, `get_my_products`, or `search_products`.
name: New product name. Omit to leave unchanged.
description: New description. Omit to leave unchanged.
price: New price in whole currency units (e.g. 15.99 = €15.99). Max
100000. Omit to leave unchanged.
currency: New currency symbol. Omit to leave unchanged.
url: New merchant URL. Omit to leave unchanged.
api_key: Optional API key (`pk_*`, generate at /account).
Used when there is no OAuth token, and also when the OAuth
token lacks the required scope — an explicitly passed key
overrides an ambient token that is scoped too narrowly.
An invalid or revoked token still fails regardless. Omit when using OAuth.
Returns:
The updated product record (full, not just the changed fields), or
``{"error": ...}`` on auth/ownership/validation failure.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | ||
| name | No | ||
| price | No | ||
| api_key | No | ||
| currency | No | ||
| product_id | Yes | ||
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the idempotentHint annotation, the description details the partial-update behavior, idempotency semantics, authentication options (OAuth vs api_key), and the fallback behavior when a token lacks scope. It also discloses ownership restrictions and error conditions, going far beyond what annotations alone convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (overview, auth, behavior, args, returns). While lengthy, every sentence adds valuable information and no content is redundant or unnecessary.
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?
Comprehensive for a mutation tool with no output schema: it explains auth requirements, ownership, idempotency, parameter behavior, and the exact return value (full updated record or error). The description leaves no meaningful gaps for an agent to operate effectively.
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?
Despite zero schema description coverage, the description thoroughly explains each parameter, including units for price (whole currency units, max 100000), meaning of 'omit to leave unchanged', and the nuanced api_key fallback logic. This fully compensates for the schema's lack of descriptive text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool updates an existing product listing, specifying that only provided fields are changed. It distinguishes itself from create_product by explicitly directing users to create_product for new listings.
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 guidance on when to use this tool versus create_product, and notes the ownership requirement. This gives agents clear decision-making criteria for selecting the appropriate tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
upload_product_imageAAttach an image to an existing product by giving Partle a public URL to download the image from.
Authenticated. OAuth (scope `products:write`) preferred; `api_key` fallback.
**When to use this tool**: the image is already hosted at a public URL
(a scraped product page, an Imgur link, a CDN URL the user provided).
Partle's server fetches it and stores it.
**When NOT to use this tool**: you have local image bytes (a file the
user attached, or bytes you generated/downloaded in your sandbox).
Sending those bytes through a tool argument blows past conversation
context limits — phone-photo-sized payloads can be 6+ MB of base64.
Instead, in your code-execution sandbox, POST the file directly to the
HTTP endpoint with multipart encoding:
requests.post(
"https://partle.rubenayla.xyz/v1/external/products/{product_id}/images",
files={"file": open("/path/to/photo.jpg", "rb")},
headers={"X-API-Key": "pk_..."},
)
Or, to create the listing and attach an image in one HTTP request:
requests.post(
"https://partle.rubenayla.xyz/v1/external/products",
data={"metadata": json.dumps({"name": ..., "price": ...})},
files={"image": open("/path/to/photo.jpg", "rb")},
headers={"X-API-Key": "pk_..."},
)
Args:
product_id: ID of the product to attach the image to.
image_url: Publicly fetchable URL of the image. Server fetches it
and stores it.
api_key: Optional API key (`pk_*`, generate at /account).
Used when there is no OAuth token, and also when the OAuth
token lacks the required scope — an explicitly passed key
overrides an ambient token that is scoped too narrowly.
An invalid or revoked token still fails regardless. Omit when using OAuth.
Returns:
The created `ProductImage` record with its `id` (use for deletion)
and storage path, or ``{"error": ...}`` on validation/auth failure.
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | No | ||
| image_url | Yes | ||
| product_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses the server-side fetch-and-store behavior, authentication requirements and fallback, api_key override semantics, error behavior on invalid auth, and the return shape (ProductImage record with id and storage path). It is rich, candid behavioral detail well beyond the annotation booleans.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average, but it is well-structured with headings, bullets, and pragmatic code examples. Every section earns its place: purpose, auth, decision guidance, argument details, and return behavior. Nothing is redundant 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?
Given the 3-parameter tool, no output schema, and the need for auth guidance, the description is complete. It covers when to use, when not to use, exact auth behavior, all parameters, and return/error shapes. It even provides complete alternative HTTP requests for the local-bytes case.
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?
Even though schema description coverage is 0%, the description's Args section fully explains product_id, image_url, and api_key in plain language. It adds critical semantics like 'server fetches it and stores it' and the nuanced api_key override behavior, which the raw schema cannot convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific verb and resource: 'Attach an image to an existing product' and explains the mechanism (Partle fetches from a public URL). It is unmistakably distinct from siblings like delete_product_image or get_upload_url, and the name is reinforced by the fuller explanation.
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 provides 'When to use this tool' and 'When NOT to use this tool' sections, including the alternative of posting directly to an HTTP endpoint for local bytes. This is exemplary guidance for selecting the right tool or avoiding it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claiming 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 or an account that owns the GitHub organization, then choose Claim with GitHub.
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
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!
