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?
Beyond the annotations (which mark it as a non-idempotent write), the description discloses OAuth scope requirements, detailed non-idempotency, the dedup key behavior for external_id, the api_key override semantics, and the exact error return shape. This substantially exceeds the annotation information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and key warnings (authenticated scope, non-idempotency, required input) before diving into args. Although long, it is well-structured and every sentence adds operational value for a 15-parameter tool.
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 15 parameters, no output schema, and no enum defaults, yet the description fully explains returns, errors, authentication, default behaviors, and edge cases. It even covers nuanced behaviors like api_key fallback and external_id uniqueness, making it complete for invocation.
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 for parameter meaning. It defines every parameter's semantics, including defaults, mutually exclusive requirements (name vs product_id), the external_link single-URL rule, the external_id dedup constraint, and the condition field's typical values. This goes far 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 specific verb+resource statement ('Add an item to the caller's personal inventory') and clearly distinguishes this from update/delete siblings by framing it as the creation tool covering all lifecycle states. The intent-to-status mapping further clarifies its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context on when to use the tool: it is the single creation tool for all lifecycle states, with explicit mappings from user intent to status values. It also states required input constraints (either product_id or name) and warns it is not idempotent. While it does not explicitly name alternatives like update_inventory_item, the creation-vs-update distinction is clear from the lifecycle framing.
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.
title: Deprecated spelling of ``name``, accepted so existing clients
keep working. Pass ``name`` instead; if both are given, ``name``
wins.
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 | ||
| title | 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?
Beyond the annotations (idempotentHint=false), the description elaborates: 'Not idempotent — each call creates a new public post.' It adds essential behavioral context: required OAuth scope `inventory:write`, public feed placement, api_key fallback rules, and contact field privacy implications. 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 well-organized: purpose, usage, auth, then an Args list. Each line provides necessary information without padding. It's somewhat long due to detailed api_key explanation, but that complexity warrants it. No waste.
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 10-parameter tool with no output schema and sparse annotations, the description is exceptionally complete. It covers purpose, when to use, authentication, all parameters with semantics, return shape, and behavioral characteristics. An AI agent has everything it needs to invoke 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 schema description coverage at 0%, the description fully compensates. It explains every parameter with purpose, defaults, and relationships: name required, title deprecated and precedence rules, description use case, quantity default, currency default, contact privacy, reference_url, product_id, and detailed api_key fallback behavior. This far exceeds the schema's bare field names.
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 action: 'Post a public buy request — an ad asking suppliers to reach out.' This clearly identifies the verb, resource, and purpose. It further distinguishes from personal inventory, differentiating it from sibling tools like add_inventory_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage context: 'Use when the user wants others to know they're looking to buy something.' It also draws a clear boundary against inventory: 'Independent of personal inventory... a buy request is a sales-facing ad on the public demand feed at /wanted.' However, it doesn't name alternative tools explicitly, only implies them via the inventory contrast.
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.
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 | ||
| idempotency_key | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the annotations by detailing deduplication (409 with existing.id), idempotency key semantics, one-shot upload_url with TTL and binding, OAuth vs api_key fallback with scope details, and error response shapes. This provides deep insight into the tool's runtime behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Though lengthy, it is highly structured with clear sections (Auth, Images, Dedup, Idempotency, Args, Returns) and a code example. The purpose is front-loaded, and each sentence adds necessary operational detail that would otherwise be unavailable.
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 fully self-contained: it covers authentication prerequisites (OAuth scope and api_key fallback), the complete image upload workflow with a concrete code example, duplicate and retry handling, and documented return/error shapes. Despite having no output schema, the return values and error structures are fully specified.
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 coverage, the description fully compensates by explaining all 8 parameters, including units for price (not cents), currency default, idempotency semantics, api_key override, and store_id omission meaning. This meaning is absent from the JSON 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 'Create a new product listing on Partle,' using a specific verb (create), a clear resource (product listing), and the platform (Partle). It distinguishes itself from sibling tools by explicitly directing edits to update_product and image uploads to upload_product_image.
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 when the user wants to add an item for sale'), when-not-to-use ('For edits to an existing product, use update_product'), and alternatives for image handling (upload_product_image). It also explains duplicate-prevention behavior, preventing blind retries.
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 extensively discloses behavior beyond annotations: required OAuth scope, ownership check (404 if not owned), hard-delete semantics, detailed api_key override mechanics, and error/return formats. This adds significant value beyond the destructiveHint annotation.
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 (summary, auth, args, returns). Every sentence provides non-obvious information without unnecessary verbosity, making it both concise and highly informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter delete tool with no output schema, the description is complete: it covers authentication, ownership requirements, return payloads, error cases, and api_key edge cases. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains item_id as the row ID and provides detailed conditional semantics for api_key (when used, format, override behavior, and failure cases). Given 0% schema coverage, this fully compensates for the schema's lack of descriptive detail.
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 function: 'Permanently delete an inventory row.' It specifies the resource (inventory row) and the action (permanent delete), distinguishing it from sibling tools like update_inventory_item and delete_product.
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 context for use (permanent, hard delete) and prerequisites (auth, ownership), but it does not explicitly mention alternatives or when not to use this tool. The 'no soft-delete' note implies other options, but no concrete comparison is given.
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 the annotations (destructive, idempotent), the description discloses irreversible deletion, no soft-delete/trash, OAuth scope requirements with api_key fallback logic, ownership constraints, and idempotent error behavior. This goes well beyond 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: an opening summary, clear usage conditions, an Args list, and a return-value block. Every sentence contributes unique and necessary information 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?
The description covers authentication, required scope, ownership, idempotency, error behavior, and the exact return format. Given the tool's destructive nature and lack of output schema, this is thoroughly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though the schema is minimal (0% coverage), the description's Args section fully explains both parameters: product_id is sourced from get_my_products, and api_key includes generation path, fallback precedence, and override behavior. This adds meaning far 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 opens with a specific verb+resource: 'Permanently delete a product listing and all its images.' This clearly states the action and scope, and distinguishes it from sibling tools like delete_inventory_item or delete_product_image.
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 only when the user explicitly asks to remove a listing they own' and 'Caller must own the product.' This sets clear conditions for tool selection and prerequisites.
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?
Builds on the annotations by detailing the scope of destruction ('only the image record and its file are removed'), explaining authentication requirements, OAuth scope, api_key fallback behavior, and that invalid tokens still fail. This goes well beyond the destructiveHint/idempotentHint flags.
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?
Well-structured with clear sections for purpose, usage, arguments, and returns. Every sentence adds value with no filler. The length is appropriate for the complexity of the operation.
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?
Provides a complete picture: purpose, when to use, auth requirements, parameter semantics, return format, and error behavior. The description covers all necessary context despite the absence of 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?
The input schema has 0% description coverage, but the description fully documents each parameter: product_id, image_id (including where to find it), and api_key (with prefix, generation location, and override semantics). 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 opens with a specific verb and resource: 'Remove a specific image from a product.' It also distinguishes itself from the sibling delete_product by explaining that the product itself is preserved and pointing to delete_product for product removal.
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 ('when an image was uploaded by mistake or the merchant updated their listing') and provides an alternative ('To remove the product entirely use delete_product'). Also includes authentication guidance.
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?
The description goes far beyond the readOnlyHint annotation by detailing authentication requirements (OAuth scope, api_key fallback), default behavior (all statuses returned), pagination defaults, and exact error response shape. It also explains the nuanced api_key behavior regarding token scopes, which is highly valuable for the agent.
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 (Args, Returns) and concise bullet-like lines. It is longer than average, but every sentence adds necessary detail—no fluff or redundancy. The structure makes it easy to scan.
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 no schema-level descriptions, this description is remarkably complete. It covers authentication, filtering, pagination, return format, and error handling. The agent has everything needed 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?
Schema coverage is 0%, but the description explicitly defines every parameter: status (with an enumeration), product_id, project, q (case-insensitive substring search), limit (1–200 range), offset, and api_key (including format and behavior). 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 a clear action: "List the caller's personal inventory items." This distinguishes it from sibling tools like get_my_products (products vs. inventory items) and get_product (single item). It also explicitly notes the default behavior of returning all statuses, further clarifying scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete example user queries ("what do I own?", "what's on my wishlist?", etc.) and states "Use this when..." providing clear context. However, it does not explicitly mention when not to use this tool or name alternative sibling tools, so it falls short of a full 5.
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?
Despite annotations already declaring readOnlyHint=true, the description adds substantial behavioral context: authentication requirements (OAuth scope `products:read` vs api_key fallback), the override semantics of an explicitly passed key, failure behavior for invalid/revoked tokens, and the exact error response shape on auth failure. This goes 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?
The description is organized with clear sections (purpose, auth, usage, args, returns) and every sentence contributes new information. It is detailed without being bloated, and its structure allows quick scanning.
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 2-parameter read-only tool, the description covers all critical aspects: purpose, auth, usage context, parameter ranges, return shape, and error handling. The presence of an output schema further reduces the need to explain return values, and the description still notes how the output relates to `search_products`.
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 compensates: `limit` gets its range (1–200) and default, and `api_key` receives rich semantics including when to use it (missing OAuth scope, no token), override behavior, and when to omit it. This adds meaning far 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 opens with 'List products created by the authenticated user,' a specific verb+resource+scope that clearly identifies the tool's function. It also explicitly distinguishes itself from `search_products`, which searches the public catalog without owner scoping.
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 provides explicit usage context ('Use when the user asks "what have I listed?" or before bulk operations') and names the alternative tool (`search_products`) with why it differs. This gives clear when-to-use and implicit when-not-to-use guidance.
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 include readOnlyHint=true; the description reinforces this with 'Read-only. No authentication.' and adds return behavior—including the canonical partle_url and an error object for nonexistent IDs—that is not in the schema or 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 compact and front-loaded: first sentence states the core purpose, followed by usage guidance, then security/return details. Each line adds new information without redundancy; the Args/Returns sections are properly labeled and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read operation with no output schema, the description covers all necessary aspects: purpose, contextual trigger, parameter semantics, return value, error handling, and auth requirements. Combined with the readOnlyHint annotation, the agent can safely 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 only specifies product_id as an integer. The description explains its provenance ('Integer id from a search_products result, or visible in a Partle product page URL (/p/<id>-<slug>)') and clarifies the expected format, covering 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?
States the exact action: 'Get the full record for a single product by its numeric ID.' Uses a specific verb and resource, and explicitly contrasts with summary-level search results by mentioning 'full record' and fields like sold status, which distinguishes it from sibling tools like 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?
Explicitly tells when to use: 'Use after search_products returns a candidate...' and what not to do: 'Don't loop get_product over many search results — re-search with tighter filters instead.' Names the alternative tool and gives a decision rule.
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?
Beyond the readOnlyHint annotation, the description discloses that no authentication is required, the tool is cheap but rarely changes (suggesting caching), and it describes the exact return structure. This provides valuable context about performance and data freshness.
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, front-loaded with the main purpose, and every sentence adds meaningful information. It is appropriately concise while covering usage, alternatives, behavioral notes, and 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 the tool's simplicity (no parameters, no output schema), the description covers all necessary aspects: purpose, usage, alternatives, behavioral characteristics, and return shape. It is fully complete for an agent 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 zero parameters, the schema provides no parameter info. The description compensates by fully explaining what the tool returns (total_products, total_stores, description), giving the agent a clear understanding of the tool's output without needing parameters.
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: 'Get top-level Partle platform statistics.' It distinguishes itself from sibling tools by explicitly noting 'no per-product or per-store data' and directing users to search_products/search_stores for those details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the tool (e.g., 'size questions') and explicitly names alternatives ('use search_products / search_stores for that'), covering both when and when-not usage.
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?
Beyond the readOnlyHint annotation, the description adds critical behavioral context: 'Read-only. No authentication.' It also discloses the return behavior and error handling: 'Returns a single store object with all fields. Returns {"error": ...} if the ID does not exist.' This fully informs the agent about side effects, auth requirements, and failure modes.
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 paragraphs for purpose, usage, arguments, and return value. It is concise (~120 words) and every sentence adds value: the usage guidance, the alternative tool mention, and the error response are all necessary. Nothing is 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?
Despite a lack of output schema, the description fully covers what the tool does, when to use it, what parameters mean, and what to expect in return (including error cases). It also mentions the scope (store metadata only) and the no-auth requirement, making it 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?
The input schema only defines store_id as an integer with no description (coverage 0%). The description compensates fully by explaining it is 'Integer `id` from a `search_stores` result,' providing source context and how to obtain the value. This adds meaning beyond the raw schema type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get the full record for a single store by its numeric ID,' which is a specific verb ('Get') on a clear resource ('store record') and distinctly separates it from sibling tools like search_stores and get_product. It also clarifies the ID type ('numeric ID'), leaving no ambiguity about the tool's core function.
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 usage: 'Use after search_stores to retrieve fields not in the search summary' and provides a direct alternative for a different need: 'For a list of *products* in that store, call search_products(store_id=…) instead.' This clearly defines when to use and when not to use the tool, naming the alternative.
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?
The description discloses auth requirements (OAuth scope products:write, api_key fallback and override behavior), URL validity (~15 min), the exact PUT call with headers, and that no auth header is needed on the PUT because the URL is the credential. It also explains error cases (auth/ownership failure). This goes well beyond the sparse 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 efficiently organized with bolded labels, code blocks, and bullet examples. Every section (auth, when to use, PUT instructions, args, returns) earns its place. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 2 parameters, no output schema, and moderate complexity, the description is complete: it covers auth flows, exact HTTP call, response shape, error cases, validity window, and sibling alternatives. An agent can invoke this correctly without external docs.
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?
Although schema description coverage is 0%, the description provides thorough explanations for both parameters: product_id must be owned and identifies the target; api_key is optional, used when no OAuth token or when OAuth token is insufficient, and explicitly overrides an ambient scoped token. 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 'Mint a one-shot signed upload URL for a product you own,' specifying the action (mint), resource (upload URL), and target (product). It clearly distinguishes this from sibling tools by emphasizing local image bytes vs. public URL and referencing the 409 conflict case from create_product.
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 (local image bytes for an existing product), gives common cases (create_product 409, adding additional photos), and provides a direct alternative: 'If you have a public URL, use upload_product_image instead.' This is model guidance.
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?
Discloses authentication requirements, OAuth scope, ownership requirement, atomicity, API key fallback behavior, and the return shape ('updated inventory row, or error'). The annotations only provide readOnly/idempotent/destructive hints, so this description substantially adds behavioral context without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a lead purpose sentence, context, auth note, then a clear Args list and return value. Every sentence is informative; the minor 'three columns' vs four fields is a small slip but not distracting.
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 five-parameter tool with no output schema, the description covers auth, return value, parameter semantics, and relationships to siblings. No critical behavioral context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero parameter descriptions, but the Args section explains each parameter's meaning, format (e.g., 'whole units, not cents'), requiredness, defaults, and special API key semantics, fully compensating for the 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 specific action: 'Move an inventory item to status=for_sale and set listing fields.' It names the resource and target state, and distinguishes itself from `update_inventory_item` as a convenience wrapper, making its purpose unambiguous relative to 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 explicitly frames itself as a wrapper over `update_inventory_item` for natural user requests, and lists prerequisites (OAuth scope, ownership). This tells the agent when to pick it over the general update tool. No exclusion is stated, but the context is clear.
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?
Annotations provide readOnly=false, idempotent=true, destructive=false. The description adds crucial context: OAuth scope requirement, ownership requirement, detailed api_key override behavior (including fallback when token lacks scope, and failure on invalid/revoked keys), and return format. This goes well beyond what annotations 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?
Well-structured with clear sections: summary, context, auth, args, returns. Each sentence adds necessary information without redundancy. Despite being detailed, it remains focused and easy to parse.
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 2-parameter tool with no output schema, the description covers everything needed: purpose, alternative tools, authentication, parameter details, and return value/error behavior. 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 input schema provides only names and types for item_id and api_key, with 0% description coverage. The description compensates fully: item_id is explained as 'ID of the inventory row', and api_key is given thorough guidance on format, optional usage, override semantics, and failure conditions.
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 'Mark an inventory item as sold (status=sold)' with a specific verb and resource. It distinguishes itself from siblings by being labeled a convenience wrapper over update_inventory_item, making its specialized role obvious.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names update_inventory_item as the general alternative and frames this as the natural 'I sold the drill' request. Also gives prerequisites (authenticated, required scope, ownership), guiding when and why 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.
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 already signal read-only and open-world, but the description goes far beyond: 'Read-only. No authentication. Rate-limited to 100 requests/hour per IP,' explains latency differences between modes, describes null-priced row behavior, and warns about relevance_score calibration. 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?
Though long, the description is tightly organized with headers, bold mode labels, and bullet-like paragraphs. The opening delivers the purpose and critical search instruction first. Each section earns its place; the length is justified by the tool's 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?
Given 11 parameters, one required, and an output schema that is not shown, the description covers all aspects: when to use, parameter meanings, return value fields (including partle_url), caveats about relevance_score, and pagination. There is no missing information for an agent to invoke this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but the description fully compensates. Every parameter (query, min_price, max_price, tags, store_id, sort_by, has_price, semantic, super_search, limit, offset) has a detailed explanation, practical examples, and edge-case behavior. 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 opening line states the verb and resource: 'Search Partle's product catalog by name or description.' It distinguishes from sibling tools by explicitly saying 'Prefer over search_stores when the intent is product-led' and suggests 'Use get_product afterwards if the user wants full details for one specific result.'
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: 'Use this when the user asks to find a specific product or browse products matching a query,' names the alternative (search_stores) and the follow-up (get_product), and gives detailed heuristics for choosing between default and super_search modes. This is textbook usage guidance.
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?
While annotations already mark readOnlyHint=true, the description adds valuable behavioral context: no authentication required, a specific rate limit (100 requests/hour/IP), and how the tool behaves when query is omitted. It also discloses return-field behavior, enriching beyond the structured 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 well-structured with a purpose statement, usage guidance, behavioral notes (read-only/rate-limit), a dedicated Args section, and a Returns section. Every sentence provides operational value, and the formatting is clean and 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?
The description covers authentication, rate limits, parameter behavior, return fields, and how to chain with search_products. It gives a concrete example query, making the tool fully actionable for an agent without needing additional lookup.
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 full responsibility for parameters. It provides clear semantics: query is free-text over store name/address, and limit is 1-50 with a default of 20. 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 specific verb+resource pairing: "Search or list stores in the Partle marketplace." It further differentiates from sibling tools by explicitly directing product-led questions to search_products, making the tool's scope 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 clearly states when to use this tool (store-led questions) and when not (product-led questions, use search_products instead). It also instructs that omitting the query browses the whole catalog, providing concrete usage context.
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?
Adds behavioral detail beyond readOnly and openWorld annotations: read-only, no authentication, rate limit 100 req/hour, pagination order (newest first), and that Partle does not broker contact. Also flags the deprecated 'title' field.
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?
Well-structured with intro, usage context, behavioral notes, and explicit Args/Returns sections. No filler; every sentence adds value. Length is appropriate for the tool's richness.
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 return fields in detail (including markdown, contact usage, deprecated field), behavior, auth, rate limits, and pagination. Despite having an output schema, it explains things the schema might not convey (e.g., how to respond to requests).
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 only lists parameters with types/defaults, so the description provides all semantic meaning: query is case-insensitive substring over name+description, limit range 1-100, offset pagination. Fully compensates for 0% schema 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?
Clearly states the tool browses public buy requests (the demand side of Partle). Distinguishes from siblings by specifying it is for unmet demand and cross-referencing with 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?
Explicitly says when to use: to offer matches against search_products or survey unmet demand. Also clarifies these are public postings and independent of private inventory, setting context against other tools.
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?
Beyond annotations (which are sparse), the description discloses authentication requirements, OAuth scope, fallback api_key behavior, attribution to the account, and de-duplication within 24h. It also explains the return payload and error cases. This far exceeds the minimal safety profile conveyed by `readOnlyHint: false`, `idempotentHint: false`, and `destructiveHint: false`. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Although long, every section earns its place: purpose, auth, scope, exclusions, dedupe, args, returns. Logical headings and bullet lists make it scannable. The front-loaded sentence immediately states the tool's function, and the structure prevents 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 moderate complexity, no output schema, and sparse annotations, the description covers everything an agent needs: input constraints, auth flows, return format, error cases, and behavioral edge cases like deduplication. It is a complete standalone reference.
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% (no descriptions in schema), so the description carries full responsibility. It explains `feedback` with character limit and advice to be specific, and `api_key` with prefix, purpose, override behavior, and when to omit. This fully compensates for the schema's silence.
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 'Report a problem with the Partle marketplace API/MCP itself', a specific verb+resource that clearly distinguishes it from the sibling tools like create_product or search_products. It further clarifies scope with 'what this is for' and 'what this is NOT for', leaving no ambiguity about the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance via the 'Scope' bullet list and explicit when-not-to-use with counterexamples. It even advises against submitting feedback for user-request failures and mentions de-duplication, giving the agent clear decision criteria. No alternatives among siblings are relevant, but exclusions are detailed.
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 (readOnlyHint false, idempotentHint true, destructiveHint false), the description adds essential behavioral context: required OAuth scope, ownership requirement with 404 semantics, idempotence details, API key override behavior, and error return formats. This exceeds what annotations alone 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 well-organized: one-line purpose, auth/ownership, idempotence, lifecycle alternatives, args, and returns. Each section earns its place; no redundant filler. It front-loads the primary action and uses clear formatting for parameters.
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 16 parameters and no output schema, the description covers all key aspects: patch behavior, auth requirements, error handling, idempotence, and how to get/use item_id. It also explains API key fallback, making the tool usable without external docs. The only minor gap is full per-field description, but that is mitigated by referencing the sibling 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 coverage, the description compensates by explaining the two non-obvious parameters (item_id and api_key) and the patch semantics ('omit any field you don't want changed'). However, it defers all other parameter definitions to add_inventory_item rather than describing them directly, which leaves some ambiguity if that sibling tool's description isn't accessible.
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 is a specific verb (patch) and resource (inventory item). It distinguishes itself from siblings by directing lifecycle convenience to mark_for_sale and mark_sold, making clear this tool is for general partial updates.
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 names alternatives for lifecycle operations ('For lifecycle convenience, see mark_for_sale and mark_sold'), implying when to use this tool vs those. It also explains how to obtain item_id and notes that omitting fields leaves them unchanged, providing clear context for when to invoke.
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?
Despite annotations already indicating idempotency, the description adds crucial behavioral details: partial-update semantics (omitted fields preserved), idempotent final state, ownership validation error, and nuanced OAuth/api_key fallback behavior including override and invalid-token failure. This is substantially more than 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 well-structured with clear sections (summary, auth, behavior, args, returns). It is long but every sentence adds value—auth details, ownership, idempotency, and parameter explanations are all necessary. The first sentence immediately states purpose, and the rest is tightly organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and 7 parameters, the description provides everything needed: full return type (updated product record or error), error conditions (auth/ownership/validation), usage prerequisites, and parameter semantics. It leaves no significant gap for an agent 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?
Schema coverage is 0%, so the description carries full burden. It thoroughly explains all 7 parameters: product_id sourcing (from create_product, get_my_products, or search_products), omit-to-leave-unchanged for each field, price format with example and max, and api_key's fallback/override semantics. 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 and resource: 'Update an existing product listing. Only provided fields are changed.' It clearly differentiates from sibling create_product by stating 'For creating a new listing, use create_product instead.' This fully establishes the tool's purpose and scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly contrasts with create_product, providing a direct alternative. It also specifies the ownership precondition ('Caller must own the product') and auth requirements, giving clear context on when and how to use. This goes beyond minimal guidance.
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?
The description discloses authentication requirements (OAuth scope products:write preferred, api_key fallback), details how api_key overrides an insufficient OAuth token, and notes failure conditions ('An invalid or revoked token still fails regardless'). It also explains the return value (ProductImage record or error). These behavioral details go 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?
The description is longer than average but well-structured with bolded sections ('When to use', 'When NOT to use', Args, Returns). Every section serves a purpose, though the two code examples add length. It is front-loaded with the core purpose and auth note before diving into details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description explicitly documents the return value. Given the tool's complexity (auth, multiple upload modes, alternative endpoint), the description covers all essential context: purpose, auth, usage guidance, parameter semantics, and failure modes. It is fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description includes an extensive Args section explaining each parameter: product_id (ID to attach to), image_url (publicly fetchable URL), and api_key (optional, fallback auth with override behavior). This fully compensates for the empty 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 clearly states the tool's function: 'Attach an image to an existing product by giving Partle a public URL to download the image from.' It specifies the verb (attach), resource (product image), and method (public URL). This distinguishes it from siblings like delete_product_image and get_upload_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?
Explicit guidance is provided: 'When to use this tool' (image hosted at public URL) and 'When NOT to use this tool' (local bytes), with a concrete alternative HTTP endpoint for uploading local files. This leaves no ambiguity about when this tool is appropriate versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
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!
