Sous

Overview Schema Source Related Servers Discussions Admin

Core 2/4: Search the catalog

search_products

Read-onlyIdempotent

Find products in Valio Aimo's catalog by name, brand, or ingredient in Finnish, Swedish, or English, with filters for dietary claims, allergens, labels, temperature, origin, and food-only status.

Instructions

Search Valio Aimo's catalog (17.5k products) by name, brand or ingredient in Finnish, Swedish or English.

claims: required nutritional claims, e.g. FREE_FROM_LACTOSE, FREE_FROM_GLUTEN, VEGAN. avoid_allergens: GS1 codes to exclude, e.g. AM (milk), AN (tree nuts), AP (peanuts), AW (gluten), AE (egg). Group codes cover the family (AN = all tree nuts). Products that contain them are dropped; products with no allergen data are kept but marked 'unknown'. Full list: resource sous://allergens. labels: e.g. GOODS_FROM_FINLAND_BLUE_SWAN, EU_ORGANIC_FARMING, MARINE_STEWARDSHIP_COUNCIL_LABEL. temperature: ambient, chilled or frozen. food_only: default ranks food first (equipment first only when the query names it, e.g. "milk jug"); true drops non-food (tableware, cleaning, disposables); false = no preference. origin: keep only products declared from these countries or groups, e.g. ["fi"], ["EU"], ["NORDIC"]; the country is supplier-declared (not verified) and products without one drop out. Every card and quote line carries country_of_origin. Synonyms work across languages: "butter" also finds voi / smör. Returns {products: [card], note}: cards without price or stock; pass several of the ids to request_quote next.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "search_products"
  }
}

Input Schema

Name	Required	Default
`limit`	No
`query`	Yes
`claims`	No
`labels`	No
`origin`	No
`agent_id`	No	anonymous-agent
`food_only`	No
`temperature`	No
`avoid_allergens`	No

Output Schema

Name	Required	Description	Default
`note`	Yes
`products`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.0Nov 15, 2026

TDQS

A4.1/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and closed-world scope, so the safety profile is covered. Beyond that the description adds genuinely useful behavior: cards come without price or stock, allergen-less products are kept but marked 'unknown', and origin is supplier-declared and unverified. Missing detail on result ordering/pagination and on the 'note' field's meaning keeps this from the top.

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?

Front-loads the one-sentence purpose, then uses a compact label-per-line format that is easy to scan, with cross-language synonym behavior and return shape at the end. Slightly loose phrasing ('claims: required nutritional claims') and an unlabeled parameters block cost a point.

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?

For a 9-parameter search with read-only annotations and an output schema, the description covers the semantics an agent needs to filter correctly and warns about data-quality caveats on allergens and origin. Only limit/pagination and agent_id semantics are absent, which is a minor but noticeable omission.

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 0%, so the description must carry all parameter meaning, and it does for the non-obvious ones: claims, avoid_allergens with GS1 code examples and group-code behavior, labels, temperature values, food_only tri-state, and origin groups. It leaves limit and agent_id undocumented, which is a real gap for a 9-parameter tool, though query and limit are largely self-evident.

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?

States a specific verb and resource ('Search Valio Aimo's catalog') plus scope (17.5k products, name/brand/ingredient, three languages), which is enough to separate it from retrieval-by-id tools like get_product. It also names the downstream consumer, request_quote, tying the tool into a workflow.

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?

Gives clear operational context per filter (e.g. food_only's default ranking with the 'milk jug' example, origin group semantics) and instructs 'pass several of the ids to request_quote next'. It does not explicitly say when to prefer a sibling over this search (e.g. known-id lookups via get_product), so no exclusion guidance.

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

Deploy Server