Sofala marketplace

Search listings

search_listings

Read-onlyIdempotent

Search the live listings. Give a few words, and filters when the person mentioned them. Returns a few well-matched results; compare them for the person rather than listing everything. Prices are in each listing's own currency. Adult (18+) listings are left out unless category is adult or one of its subcategories.

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_listings"
  }
}

Input Schema

Name	Required	Description
`city`	No
`near`	No	Only listings with a map pin within radius_km (default 25) of this point.
`page`	No
`sort`	No	nearest needs near.
`limit`	No	Default 10.
`query`	No	Words to look for, e.g. "bamboo armchair".
`region`	No	State, province or district (matches part of it).
`country`	No	ISO country code.
`category`	No	Category slug from list_categories (top level includes its subcategories).
`delivery`	No	Only listings offering this.
`condition`	No
`max_price`	No	Highest price.
`min_price`	No	Lowest price.
`attributes`	No	Filters on attributes from get_category, such as {"make": "BMW", "year": {"min": 2015}, "fuel": ["diesel", "hybrid"]} or {"grading": "psa", "grade": {"min": 9}}: enum and text take a value or a list (text matches part of the value), numbers {"min": , "max": } or one value, yes/no true or false, fits_years one year (parts that fit it), serial {"max": } (print run).
`postal_code`	No	Postal code or its start, such as 1100 or SW1A.

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 3, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds two genuinely non-obvious behaviors: results are a curated subset rather than exhaustive, and prices are in each listing's own currency, so no cross-listing price comparison is implied. The adult-content suppression rule with its category exception is also disclosed. It does not mention pagination limits or what happens when nothing matches.

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

Conciseness5/5

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

Four short sentences, front-loaded with purpose then usage then two caveats (currency, adult filtering); every sentence carries distinct information with no restatement of the name or title.

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

Completeness3/5

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

For a 15-parameter tool with a nested attributes object and no output schema, the description leaves real gaps: the return shape is only "a few well-matched results", and nothing explains pagination/limit interaction or how to broaden a search that returns too little. The behavioral notes it does include are valuable, but they do not fully cover a tool of this complexity.

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?

With ~80% schema coverage the baseline is 3, but the description adds interpretation the schema cannot: min_price/max_price operate in per-listing currencies, and the category parameter silently flips the adult-content filter on. The vague "filters when the person mentioned them" does not map to the 15 specific parameters, so it is not a full substitute for schema detail.

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

Purpose5/5

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

"Search the live listings" names a specific verb (search) and resource (listings), and "Returns a few well-matched results" makes clear it is a multi-result discovery tool, distinct from the single-item get_listing and the taxonomy tools list_categories/get_category.

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 tells the agent how to drive the tool ("Give a few words, and filters when the person mentioned them") and how to handle output ("compare them for the person rather than listing everything"), which is real usage guidance. It stops short of naming alternatives such as get_listing for full detail on a chosen result, so no explicit when-not-to-use routing.

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

All Sofala marketplace tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?