within

Search clothes, shoes and bags in stock

search_pieces

Read-onlyIdempotent

Find in-stock new and pre-owned clothes, shoes, bags, jewellery, watches, and home objects at independent luxury boutiques, filtered by designer, category, size, price, city, and men's or women's.

Instructions

Search what is in stock right now at independent luxury boutiques: clothes, shoes, bags, jewellery, watches and home objects, new and pre-owned. Each result has the price in the boutique's currency, the sizes in stock, the shop that has it and the shopwithin.co page to buy it. Use this when someone wants to find or shop for an item, a designer's items, something in their size or under a price, or what is in stock in a city. A plain sentence works as the query (prices like 'under $400' and 'cheapest' are understood); designers, categories, sizes, women's or men's, boutiques, city and price narrow it. With no arguments it returns the front of the shop; lens browses new arrivals, most saved, or marked down. It reads only the boutiques on within, not mass market stores, and gives no style advice.

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": "search_pieces"
  }
}

Input Schema

Name	Required	Description
`city`	No	The city the boutiques are in, e.g. 'Toronto': a place to shop, not the shopper's own location. If within has no boutiques there yet, the answer says so and names the cities that have them.
`lens`	No	Browse a shelf instead of searching: 'new' = just arrived, 'trending' = what people are saving, 'sale' = marked down. Ignored when a query or filters are given.
`sort`	No
`limit`	No	Pieces per page, default 12.
`query`	No	What the shopper wants, in plain words: 'black leather loafers', 'Lemaire', 'a birthday gift for my dad under $300'.
`sizes`	No	Sizes that must be in stock, as labelled on the shelf: 'M', '42', 'US 9', 'IT 38'.
`brands`	No	Designer or house names to restrict to, exactly as they appear in results.
`offset`	No	Pieces to skip; use next_offset from the previous page.
`boutiques`	No	Boutique domains to restrict to, as shown on boutiques and pieces (e.g. 'wdlt117.myshopify.com').
`price_max`	No	Highest price to include, in the boutique's currency.
`price_min`	No	Lowest price to include, in the boutique's currency.
`categories`	No	Product types to restrict to, e.g. 'Sneakers', 'Bags'; take values from a previous result's facets.
`department`	No	Only women's or only men's.

Output Schema

Name	Required	Description	Default
`note`	Yes
`total`	Yes
`facets`	Yes
`pieces`	Yes
`view_url`	Yes
`next_offset`	Yes
`total_is_floor`	Yes
`related_searches`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.3.1Nov 11, 2026

TDQS

A4/5.0

Behavior4/5

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

Annotations already cover read-only, idempotent, non-destructive and closed-world, so the bar is lower, yet the description still adds real behavioral context: data is scoped to boutiques on within (not mass-market stores), no style advice is offered, no-argument calls return the front of the shop, and a city with no boutiques produces a message listing cities that have them. It does not repeat what annotations already declare. Pagination behavior is left to the schema's offset/limit fields.

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?

The description is front-loaded with purpose and result shape before moving to usage and constraints, and nearly every clause carries information an agent needs (currency handling, city semantics, scope limits). It is dense and long for a single tool, and the clause about lens browsing could be tightened, but there is no filler or restatement of the title.

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 13 optional parameters, four annotations and an output schema, the description covers the essentials: what is searched, what a result contains, how the free-text query is interpreted, and the data-source boundary. The output schema removes any need to describe return values in detail. The remaining gap is guidance on when to prefer this over single-piece or browsing siblings, which matters given how many exist.

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

Parameters4/5

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

Schema coverage is 92%, so the baseline is 3, and the description earns more by explaining how the query parameter behaves in practice: a plain sentence works, prices like 'under $400' and 'cheapest' are parsed, and designers, categories, sizes, department, boutiques, city and price act as narrowing filters. It also clarifies that lens is only a browse mode and is superseded by query or filters. It adds nothing for sort or offset, which the schema handles.

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 opening sentence gives a specific verb and resource with scope: search in-stock items at independent luxury boutiques, enumerating categories (clothes, shoes, bags, jewellery, watches, home objects) and condition (new and pre-owned). It also states what each result contains, so an agent knows what comes back. It stops short of naming adjacent siblings such as new_arrivals, on_sale or trending_now, which is a gap given that the 'lens' parameter duplicates those concepts.

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?

It gives explicit trigger conditions: use when someone wants to find or shop for an item, a designer's items, something in their size or under a price, or what is in stock in a city. It also defines the no-argument behavior (front of shop) and the lens fallback. What is missing is routing against alternatives ('use get_piece for one known item', 'use similar_pieces for one seed piece'), so the agent must infer those choices from sibling names.

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