within

One item in full

get_piece

Read-onlyIdempotent

Fetches full details for one shopwithin.co item by URL or boutique ID, including live sizes, stock, price, images, pickup/delivery options, and similar items before buying.

Instructions

One item in full: its description, every size with live stock, photographs, the price and any markdown, whether it can be picked up in the shop or delivered, the boutique, the page to buy it, and a few similar items. Use this when someone asks about one item from a result, pastes a shopwithin.co link, or wants to know whether a size is in stock before buying. Name the item by url, or by boutique_domain and id from a result. The url is a shopwithin.co product page link; the tool reads within's own catalog, documented at https://shopwithin.co/agents.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_piece"
  }
}

Input Schema

Name	Required	Description
`id`	No	The piece's id from a previous result.
`url`	No	A shopwithin.co piece link, e.g. https://shopwithin.co/product/<boutique>/<id>.
`boutique_domain`	No	The piece's boutique_domain from a previous result.

Output Schema

Name	Required	Description	Default
`found`	Yes
`piece`	Yes
`similar`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.3.1Nov 11, 2026

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds genuinely new behavior: the tool reads within's own catalog (documented at a URL) and can resolve the item by either a URL or a boutique_domain+id pair. It does not mention failure behavior when an identifier is stale or ambiguous.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences: contents, usage triggers, identity rules. The long enumeration of return fields partly duplicates the existing output schema, which slightly dilutes front-loading, but there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With annotations, a full input schema, and an output schema, the description's remaining obligation is identity resolution and data source, both of which it covers. It is nearly complete; only error/ambiguity behavior for identifiers is unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description does add one useful semantic beyond the schema: the url form is a shopwithin.co product page link and the boutique_domain plus id pair must come from a previous result. Otherwise it does not clarify precedence or required combinations, which the schema also leaves open (0 required params).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource precisely (one item/piece) and enumerates exactly what comes back: description, every size with live stock, photos, price and markdown, pickup/delivery, boutique, buy page, similar items. The retrieve action is implied rather than stated as a verb, and it does not explicitly contrast itself with siblings like piece_fit or similar_pieces, which keeps it short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Clear when-to-use triggers are given: when someone asks about one item from a result, pastes a shopwithin.co link, or wants to check whether a size is in stock before buying. What is missing is any when-not-to-use or named alternative (e.g. for browsing by boutique use boutique_shelf).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.