Partle
Server Details
Search products in nearby stores. Agents can also list items for sale on a user's behalf.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
- Repository
- rubenayla/partle-mcp
- GitHub Stars
- 0
- Server Listing
- Partle
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.
Tool Definition Quality
Average 4.8/5 across 21 of 21 tools scored.
Every tool targets a distinct action or resource. Inventory management (add/delete/update/mark_for_sale/mark_sold), product lifecycle (create/get/update/delete, image upload), search (products/stores/wanted, personal inventory), and utility (stats, feedback) are clearly separated. The convenience wrappers 'mark_for_sale' and 'mark_sold' are explicitly described as atomic updates, reducing ambiguity.
All tools follow a consistent verb_noun pattern using snake_case. Verbs are appropriate (add/create/delete/get/mark/search/submit/update/upload) and nouns describe the target resource. There is no mixing of conventions or unclear abbreviations.
With 21 tools, the server covers personal inventory, product listing, marketplace search, buy requests, and platform utilities. Each tool serves a clear purpose without redundancy, and the scope matches the domain well.
The tool surface provides full CRUD for inventory and products, plus search and convenience methods. A minor gap exists: buy requests can be created and searched but not updated or deleted. Otherwise, the domain is well-covered.
Available Tools
21 toolsadd_inventory_itemAInspect
Add 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: Legacy/fallback auth.
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 |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states 'Not idempotent — each call creates a new row,' which aligns with and adds to the annotations (idempotentHint=false). It also mentions required auth and OAuth scope, providing transparency beyond 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 thorough but well-structured with headers, examples, and bullet points. Every sentence provides necessary guidance given the complexity (15 parameters). Slightly verbose, but justified for clarity.
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 15 parameters, no output schema, and no annotations beyond readOnly/idempotent/destructive hints, the description covers all aspects: parameter details, return structure (new inventory row with embedded product), error handling, and usage examples. It is fully complete for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining every parameter's purpose and usage. Examples include the status lifecycle, notes as a 'dumping ground,' external_id as dedup key, and constraints on external_link. This adds immense meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Add an item to the caller's personal inventory.' The verb 'Add' and resource 'inventory item' are specific, and the tool is well-differentiated from siblings like delete_inventory_item and update_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?
The description provides extensive usage guidelines: authentication and OAuth scope requirements, non-idempotent behavior, how to choose between name and product_id, how to set status based on user intent, where to place extra URLs, and the dedup function of external_id. It implicitly distinguishes from other tools by focusing on creation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_buy_requestAInspect
Post 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:
title: Short scannable headline ("Looking for X").
description: Markdown 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: Legacy/fallback auth.
Returns:
The newly-created buy request, or ``{"error": ...}``.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| api_key | No | ||
| contact | No | ||
| currency | No | € | |
| quantity | No | ||
| max_price | No | ||
| product_id | No | ||
| description | No | ||
| reference_url | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds value beyond annotations: it declares non-idempotence ('Not idempotent'), required auth scope ('inventory:write'), and independence from inventory. Annotations do not contradict; they complement. This provides full behavioral transparency.
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?
Description is well-structured with clear sections (purpose, usage, auth, args, returns) and front-loaded with key information. Each sentence adds value, though some parameter details could be slightly condensed. Still very efficient.
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 complexity (9 params, no output schema), the description explains all inputs and gives a high-level return value. It lacks detailed structure of the returned object, but for a creation tool, this is sufficient. Overall complete for context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, so the description carries full burden. It provides detailed, clear explanations for each parameter (title, description, quantity, etc.) with practical guidance (e.g., 'supplier reads this to decide'). This significantly aids correct parameter usage.
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?
Description clearly states it posts a public buy request as an ad for suppliers, and explicitly distinguishes it from personal inventory tracking. The verb 'create' and resource 'buy request' are specific, and the context of the public demand feed differentiates 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?
Description explicitly states 'Use when the user wants others to know they're looking to buy something' and contrasts with personal inventory. It provides clear context but could be improved by explicitly stating when not to use (e.g., for direct supplier contact).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_productAIdempotentInspect
Create 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: Legacy/fallback auth. 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 |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Provides extensive behavioral details beyond annotations: authentication methods and required scope, image handling constraints, duplicate prevention with 409 response, idempotency with key, and response structure including error formats.
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 (auth, usage, images, dedup, idempotency, args). Slightly long but every section adds value; no wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary aspects for a complex tool: authentication, parameter details, error handling, duplicate prevention, idempotency, image attachment flow, and return values, despite no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schemas have 0% description coverage, but the description thoroughly explains each parameter's purpose, constraints (e.g., name length, price units, currency examples), and defaults, fully compensating.
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 explicitly states 'Create a new product listing on Partle.' It clearly defines the verb and resource, and distinguishes from sibling tools like update_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?
Directly says 'Use when the user wants to add an item for sale. For edits to an existing product, use update_product instead.' Also mentions alternatives like upload_product_image for images.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delete_inventory_itemADestructiveIdempotentInspect
Permanently 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: Legacy/fallback auth.
Returns:
``{"deleted": true, "id": item_id}`` on success, or
``{"error": ...}`` on auth / not-found.
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | No | ||
| item_id | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint=true, idempotentHint=true), it adds OAuth scope, ownership requirement, and exact return format, covering error conditions.
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 authentication, arguments, and return values. Concise yet comprehensive with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Fully covers purpose, authentication, permissions, error cases, and return format. Adequate for a simple delete tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description compensates fully: item_id explained as 'ID of the row to delete' and api_key as 'Legacy/fallback auth', adding meaning beyond the schema's types.
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 'Permanently delete an inventory row' with a specific verb and resource, distinguishing it from siblings like add_inventory_item or update_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?
It provides explicit context: authenticated, required OAuth scope 'inventory:write', caller must own item (404 otherwise), hard delete (no soft-delete). This helps the agent decide when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delete_productADestructiveIdempotentInspect
Permanently 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: Legacy/fallback auth. 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 |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint and destructiveHint. The description adds behavioral details like idempotency semantics and OAuth scope, but repeats 'Destructive' which is already in annotations. Slight redundancy but still adds value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections, each sentence is purposeful. No fluff. Front-loaded with the action and key constraints.
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 provides return format. Covers auth, ownership, idempotency, and destructive nature. Complete for a simple 2-param tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description explains both parameters clearly: product_id comes from get_my_products, api_key is legacy auth and should be omitted when using OAuth. This compensates fully.
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 action (permanently delete), the resource (product listing and all its images), and distinguishes from sibling tools like delete_inventory_item and delete_product_image by focusing on the listing itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use only when the user explicitly asks to remove a listing they own' and warns about irreversibility. Also notes caller must own the product, providing clear context for when to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delete_product_imageADestructiveIdempotentInspect
Remove 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: Legacy/fallback auth. 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 |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the description does not need to repeat those. However, it adds useful behavioral context: the product is preserved, only the image record and file are removed, and it confirms idempotency. This provides more detail than the annotations alone, though the annotations already cover the main behavioral traits.
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 relatively long but well-structured with a clear verb first, then usage guidance, then parameter explanations. Every sentence adds value. Minor redundancy (e.g., 'Destructive, idempotent' repeats annotations) but overall earns its length. Could be slightly more concise, but it is effective.
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 has 3 parameters and no output schema, the description covers all aspects: what it does, when to use, what not to use (sibling tool), parameter semantics with examples, return format, and error conditions. It also provides authentication details. This is complete and leaves no critical gaps for an AI 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?
The input schema has 0% description coverage, so the description must carry the full burden. It explains each parameter: product_id as the product's ID, image_id as the image ID visible in get_product responses, and api_key as legacy/fallback auth. This adds significant meaning beyond what the schema provides, enabling correct parameter usage.
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 'Remove a specific image from a product' with a specific verb and resource. It clearly distinguishes itself from the sibling tool 'delete_product' by noting that the product itself is preserved. This makes the tool's purpose unambiguous and differentiates it from alternatives.
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 says 'Use when an image was uploaded by mistake or the merchant updated their listing' and provides a direct alternative: 'To remove the product entirely use delete_product'. This gives clear guidance on when to use this tool versus its sibling, and also includes authentication context (OAuth preferred, api_key fallback).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_my_inventoryARead-onlyInspect
List 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: Legacy/fallback auth. 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 |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description focuses on adding value: authentication details (OAuth scope, api_key fallback), default behavior (returns all statuses if none specified), return structure including error handling, and parameter behavior. 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 with clear sections (summary, auth, usage, args, returns). Every sentence provides necessary information; no redundancy. It is appropriately sized for a complex tool with many optional 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 no output schema, the description adequately includes return structure ('items', 'count') and error format. It covers authentication, filtering, pagination, and all parameters. For a list tool with 7 optional params, this is very 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?
Despite 0% schema description coverage, the description thoroughly explains all 7 parameters: status with enumerated values, product_id, project, q (substring search), limit/offset defaults, and api_key. This fully compensates for the missing 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 'List the caller's personal inventory items' with a specific verb and resource. It also distinguishes from sibling tools by emphasizing 'caller's personal' scope, which differentiates it from other inventory-related tools like search_products or get_my_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?
The description provides explicit usage guidance by listing example user queries ('what do I own?', etc.) and mentions authentication requirements. However, it does not explicitly state when not to use this tool or name alternatives, so it misses full differentiation from siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_my_productsARead-onlyInspect
List 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: Legacy/fallback auth. 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 |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint=true, and description adds 'Read-only', authentication requirements (OAuth vs api_key), and error return shape on auth failure. 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?
Efficiently structured with front-loaded purpose, followed by usage, auth, params, and return. Each sentence adds value, though could be slightly more terse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers authentication, parameter constraints, error response, and references output shape. Adequately complete given the presence of output schema and simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, description fully compensates by explaining `limit` bounds and default, and `api_key` role as fallback, adding meaning beyond 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?
Clearly states 'List products created by the authenticated user' with a specific verb and resource. Distinguishes from sibling `search_products` by emphasizing owner scoping vs public catalog.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when the user asks "what have I listed?" or before bulk operations' and contrasts with `search_products`, providing clear when-to-use and alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_productARead-onlyInspect
Get 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 |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
States read-only and no authentication, which adds beyond the readOnlyHint annotation. Also mentions return format and error response. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise paragraph plus structured Args/Returns. Every sentence is informative with no 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 single parameter, no output schema, and minimal annotations, the description covers usage, parameter semantics, return type, and error case completely.
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 description richly explains the product_id parameter: where it comes from (search_products result or URL) and its format. Fully compensates.
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?
Clear verb+resource: 'Get the full record for a single product by its numeric ID.' Distinct from siblings like search_products and get_my_products.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when to use (after search_products when need full fields) and when not to (don't loop, instead re-search with tighter filters). Also suggests alternative tool usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_statsARead-onlyInspect
Get 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 | |||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only nature (already in annotations), no authentication needed, cheap operation, and infrequent changes with caching advice. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured: purpose first, then usage guidance, behavioral notes, and return format. Every sentence is informative with no 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 zero parameters and no output schema, the description fully explains what the tool does and returns. No gaps in information needed for an agent to use it 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?
No parameters exist; schema coverage is 100%. Description adds value by documenting the exact return format with field names and types, which is absent from the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets top-level platform statistics, specifies use cases for size questions, and distinguishes from per-product or per-store data tools like search_products and search_stores.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance (size questions) and when-not-to (use search tools for detailed data). Also includes caching recommendation for rarely-changing data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_storeARead-onlyInspect
Get 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 |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description explicitly states 'Read-only. No authentication,' which aligns with annotations (readOnlyHint: true) and adds context. It also explains error behavior for non-existent IDs, going beyond 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?
Description is concise (4 short paragraphs) and well-structured: purpose, usage, behavior, parameters, returns. Every sentence adds value 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?
For a simple tool with one parameter and no output schema, the description covers all necessary aspects: purpose, when to use, behavior, parameter meaning, and expected return/error cases. No gaps.
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 provides only the parameter name and type (integer). The description adds crucial context: 'store_id' should be the 'id' from a 'search_stores' result. While schema coverage is 0%, this single parameter is fully explained.
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 retrieves a full store record by numeric ID. It distinguishes itself from 'search_stores' (which returns summaries) and 'search_products' (for products), making its specific function unambiguous.
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 describes when to use: after 'search_stores' for full details. Also provides a clear alternative: 'search_products' for product lists. This helps the agent decide correctly between sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_upload_urlAIdempotentInspect
Mint 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: Legacy/fallback auth. 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 |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses authentication requirements (OAuth preferred, api_key fallback), URL lifetime (~15 min), and the one-shot nature. The idempotentHint annotation is not contradicted but could be clarified; overall, good behavioral context beyond 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 thorough but somewhat lengthy. It is well-structured with sections, examples, and bullet points. A slight reduction could improve conciseness without losing clarity.
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 values (upload_url, upload_expires_in, error) and provides a PUT code example. Given the complexity of signed URLs, authentication, and usage, it is highly 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?
Despite 0% schema coverage, the description's 'Args' section fully explains both parameters: product_id (what it is, ownership requirement) and api_key (legacy auth, omit when OAuth). This adds complete meaning beyond 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 clearly states the tool's purpose: 'Mint a one-shot signed upload URL for a product you own.' It lists specific use cases (handling 409 errors, adding additional photos) and differentiates itself from sibling tools like 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?
Explicitly describes when to use this tool (local image bytes, existing product) and when not to (public URL, use upload_product_image instead). Provides clear context for common scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
mark_for_saleAIdempotentInspect
Move 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: Legacy/fallback auth.
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 | € |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond annotations: it requires authentication and OAuth scope inventory:write, the caller must own the item, it sets fields atomically, and it returns the updated row or error. Annotations already indicate idempotent and non-destructive, but description fills in real-world usage behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose sentence followed by contextual explanation and an Args/Returns section. It is slightly longer than necessary but every sentence serves a purpose, and key info is front-loaded.
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 5-parameter tool with no output schema, the description covers all parameter semantics, authentication, and return value. It also notes atomicity and ownership requirement, making it fully complete for an AI agent 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 0% schema description coverage, the description carries full burden and excels: it explains item_id as inventory row ID, asking_price as whole units not cents, asking_currency defaults to €, condition is optional free string, and api_key as legacy fallback. This adds critical meaning beyond the schema's property names and types.
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 it moves an item to status=for_sale and sets listing fields, distinguishing itself as a convenience wrapper over update_inventory_item for natural user requests. It specifies the exact columns set and the optional condition field.
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 says to use when matching natural user requests like 'list my drill for sale at 30€' and mentions it is a convenience wrapper over update_inventory_item. It does not explicitly state when not to use it, 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_soldAIdempotentInspect
Mark 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: Legacy/fallback auth.
Returns:
The updated inventory row, or ``{"error": ...}``.
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | No | ||
| item_id | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description explains that it sets status to 'sold', requires authentication and specific scopes, and returns the updated row or error. This adds meaningful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear purpose statement, a usage note, auth info, and a list of args/returns. Every sentence is valuable and front-loaded.
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 operation with 2 parameters (1 required) and no output schema, the description is complete: it specifies auth requirements, ownership, return value, and the idempotent nature (implied by annotation). No gaps.
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?
Input schema has 0% parameter description coverage. The description compensates fully by explaining that `item_id` is the ID of the inventory row and `api_key` is a legacy/fallback auth parameter, adding meaning beyond 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 clearly states the action: 'Mark an inventory item as sold (status=sold).' It differentiates from sibling tools like 'mark_for_sale' (which likely sets for sale) and 'update_inventory_item' (the generic wrapper).
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 describes this tool as a 'convenience wrapper' for 'update_inventory_item' specifically for sold status, implying when to use it. It also mentions required OAuth scope and ownership, but does not explicitly list alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_productsARead-onlyInspect
Search Partle's product catalog by name or description.
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 |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only, no auth, rate limit (100/hour/IP), detailed timing for each mode, and extensive caveats on relevance_score calibration. Annotations already provide readOnlyHint and openWorldHint; description adds substantial context beyond 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?
Well-structured with clear sections, bullet points, and front-loaded purpose. Although lengthy, every sentence adds value; minimal fluff. Slightly verbose for a 5 but nonetheless efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 parameters, two modes, relevance_score nuance), the description covers all bases: usage modes, parameter details, behavior, return fields, and caveats. Output schema exists, but description still provides useful context like the partle_url recommendation.
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 description provides thorough explanations for all 11 parameters: meaning, default behavior, interaction with other params (e.g., null-priced handling with min/max_price and has_price), and practical tips. Each parameter is fully contextualized.
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 it searches Partle's product catalog by name or description. Distinguishes between default keyword and super_search modes, and explicitly contrasts with sibling tools like search_stores (product-led vs store-led) and get_product (for full 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?
Explicit guidance on when to use each mode (default for known names, super_search for descriptions), when to prefer over search_stores, and that modes are mutually exclusive. Also recommends get_product for subsequent detail retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_storesARead-onlyInspect
Search 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 |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only nature, no authentication, rate limit, and return value schema. Complements annotations (readOnlyHint, openWorldHint) with additional useful behavioral details.
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 and concise: purpose, usage, behavioral notes, parameters, return values. Every sentence adds value 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?
Complete for a simple search tool with two params and output schema. Describes return fields and how to use them (e.g., passing id to search_products). No gaps.
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 coverage, the description fully explains both parameters: query (free-text search over name/address, omit to list all) and limit (1–50, default 20). Adds meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches or lists stores, distinguishes store-led vs product-led questions, and explicitly differentiates from the sibling tool 'search_products'. Examples like 'what hardware shops are in Madrid?' reinforce 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?
Explicitly states when to use (store-led questions) and when not to (product-led, use search_products). Provides clear context for browsing the whole catalog by omitting query.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_wantedARead-onlyInspect
Browse 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 title + 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``, ``title``,
``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 |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, but the description adds useful behavioral details: rate limit of 100 req/hour per IP, no authentication, and that these are public postings. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections for purpose, usage, args, and returns. Front-loaded with purpose. Slightly verbose in return description but every sentence adds value. Could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive description covering purpose, usage, parameters, return fields, and behavioral traits. Output schema exists and the description aligns with it, making the tool fully understandable.
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 fully explains each parameter: query as free-text filter (case-insensitive, omit for all), limit range (1-100, default 20), offset for pagination. Adds significant meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is for browsing public buy requests, the demand side of Partle. It distinguishes from search_products (supply side) and notes it's sales-facing ads vs. private inventory, making the purpose unambiguous.
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: to offer matches by cross-referencing against search_products, or to survey unmet demand. Also contrasts with private inventory and notes that the contact field indicates how suppliers should respond.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
submit_feedbackAInspect
Report 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: Legacy/fallback auth. 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 |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations indicate a mutation tool (readOnlyHint=false) but not destructive. The description adds: feedback is attributed to the user's account, resubmission within 24h is deduplicated, it pages the maintainer, and it requires OAuth scope feedback:write. This goes beyond the annotations and provides valuable behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with headings (Scope, Scope NOT for, Don't loop, Args, Returns). It is front-loaded with purpose and authentication. Every sentence adds value without redundancy, making it efficient and 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 no output schema, the description provides the return format. It covers authentication, deduplication, character limits, and error types. The tool is a simple feedback submission, and the description adequately informs the agent about all necessary aspects.
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 fully compensates. It explains that feedback is freeform text up to 5000 characters and advises being specific. For api_key, it says to omit when using OAuth and describes the legacy fallback. This adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is for reporting problems with the Partle marketplace API/MCP itself. It provides specific examples of what it is for and what it is not for, which distinguishes it from all sibling tools that deal with products, inventory, stores, etc.
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 defines scope ('what this is for' and 'what this is NOT for'), gives authentication guidance (OAuth vs api_key), and warns against looping and explains deduplication. This provides clear when-to-use and when-not-to-use instructions, though it does not name an alternative tool. Still, the exclusion list is comprehensive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
update_inventory_itemAIdempotentInspect
Patch 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: Legacy/fallback auth.
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 |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description adds OAuth scope requirement, ownership verification (404 for non-owned), idempotency behavior, and return format. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is very concise, front-loaded with purpose, and every sentence adds value 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?
Given 16 parameters and no output schema, the description covers auth, idempotency, ownership, return format, and parameter references. It could be slightly more detailed on individual parameter semantics but is complete enough for agent understanding.
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 explains item_id sourcing and points to 'add_inventory_item' for other parameters. It gives minimal individual details but provides a useful reference. Baseline 4 not applicable since there are many parameters; description compensates partially.
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 does a partial update ('Patch') on an inventory item, and distinguishes itself from siblings like 'mark_for_sale' and 'mark_sold' for lifecycle convenience.
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 tells when to use this tool vs alternatives (e.g., lifecycle convenience via sibling tools), describes idempotency, and instructs how to get the item_id from other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
update_productAIdempotentInspect
Update 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: Legacy/fallback auth. 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 |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (idempotentHint=true), the description explains partial update behavior (only provided fields change, omitted preserved) and return value (full record or error). 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?
Well-structured: brief purpose, auth, behavior, alternative, arg list, return. Every sentence adds value; no redundancy. Front-loaded with critical info.
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, the description is complete: explains all params, return value, error handling, auth, ownership, and idempotency. No gaps exist.
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 adds detailed meaning for all 7 parameters: product_id source, price format/max, api_key usage, and defaults for optional fields. Fully compensates for schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates an existing product listing, uses specific verb and resource, and explicitly distinguishes from create_product: 'For creating a new listing, use create_product instead.' This ensures the agent selects the correct tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear when-to-use (updating existing product), when-not-to-use (creating, alternative create_product specified), authentication requirements (OAuth scope, fallback api_key), and ownership prerequisite. This covers both usage context and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
upload_product_imageADestructiveIdempotentInspect
Attach 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: Legacy/fallback auth. 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 |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses authentication requirements (OAuth scope, fallback), destructive hint (image upload), idempotency hint, return value structure, and error handling. 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?
Front-loaded with purpose, then auth, then usage. While detailed, every sentence adds value; minor redundancy in code examples but overall efficient.
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?
Complete coverage for a 3-param tool with no output schema: includes return value, error case, and alternative upload methods. No gaps.
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?
All three parameters are described with additional context beyond schema: product_id as ID of product, image_url as publicly fetchable URL, api_key as legacy auth fallback. Schema coverage is 0% but description fully compensates.
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 'Attach an image to an existing product' with a specific mechanism (public URL). Distinguishes from sibling tools like delete_product_image or 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?
Explicitly describes when to use (image at public URL) and when not to use (local bytes), with detailed alternatives including code examples for local file uploads.
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.
Discussions
No comments yet. Be the first to start the discussion!
Your Connectors
Sign in to create a connector for this server.