Joomil — Swiss Classifieds MCP

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

Annotations already indicate a safe read operation, and the description adds valuable context about the return format (name + French label) and the normalization pitfall (e.g., 'Bern' not 'Berne'). This goes beyond the structured data to help the agent understand expected output and potential traps.

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 three sentences long, front-loaded with the primary action, and every sentence adds essential information. It is concise without unnecessary fluff.

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 parameterless tool, the description covers purpose, usage, return values, and pitfalls. It is fully self-contained and even provides cross-references to search_classifieds, making it complete for an agent to use 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 tool has zero parameters, so the schema provides complete coverage. The description does not need to explain parameters, and the baseline of 4 is appropriate given the lack of parameters to document.

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 function: listing Swiss cantons supported by the canton filter. It distinguishes this from sibling tools by specifying the resource (cantons) and the context (Joomil's canton filter), making it 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 instructs to call this before filtering by canton and explains why (API values are non-obvious). This gives clear when-to-use guidance without needing to reference alternatives, as the use case is specific and self-contained.

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

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

Since annotations already declare readOnlyHint=true and destructiveHint=false, the description adds extra value by revealing the 'active' filter, the flat list structure, and how parent_id supports hierarchy reconstruction. This gives the agent a clear mental model of the response shape and filtering semantics, going beyond the annotated safety profile.

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?

Two sentences, no redundancy. The first states the core purpose; the second delivers all necessary parameter guidance in a compact, scannable format. Every word earns its place.

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 read-only list tool with one optional parameter, an output schema, and clear annotations, the description covers all essential aspects: what is returned (flat list with parent_id), how to filter, and the 'active' constraint. No critical information is missing.

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 already describes parent_id with 100% coverage, including the exact semantics for omission, 0, and specific IDs. The description repeats this information nearly verbatim and adds no new parameter-level insight, so it does not elevate above the schema baseline.

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 opens with a specific verb ('List') and resource ('active categories of the Joomil.ch marketplace'), clearly distinguishing this from sibling tools like get_cantons or search_classifieds. It also immediately signals the return type (flat list) and key attribute (parent_id), leaving zero ambiguity about the tool's function.

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 guidance on when to use different parameter values (omit, 0, specific ID), covering the main usage scenarios. It doesn't explicitly mention when not to use this tool or alternatives, but the domain is distinct enough that a knowledgeable agent would infer the correct choice. The parameter guidance is a strong substitute for direct alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by detailing the returned data (full description, images, category path, vendor info), which goes beyond the annotations and helps set expectations for the response.

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?

Two sentences with no redundancy: first states the operation and inputs, second lists key return fields and a usage tip. The description is front-loaded and every sentence contributes value.

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 an output schema present and only one simple parameter, the description fully covers the necessary context. It explains what is returned, ties to the search workflow, and matches the read-only nature of the tool. No gaps are apparent.

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 100% with the 'id' parameter already well described in the schema (numeric, found in URL and search results). The description does not need to add parameter details, and the baseline of 3 applies because the schema carries the full burden.

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 specifies a single classified ad retrieval by numeric ID, listing the exact fields returned (description, images, breadcrumb, vendor info, expiry, boost level). It distinguishes itself from search_classifieds by focusing on a single listing, making the purpose unmistakable.

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 instructs to use search_classifieds first to find listing IDs, providing a clear prerequisite and workflow. While it doesn't exhaustively list when-not-to-use, this guidance is sufficient for the tool's simple read-only role.

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

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

The description adds valuable context beyond the read-only annotations: it discloses pagination, field truncation (300 chars), and the fact that listings are public. This helps the agent anticipate the response shape and 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 concise, front-loaded with purpose, and every sentence adds information. It avoids fluff and is appropriately sized for the tool's complexity.

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 9 optional parameters, existing output schema, and annotations, the description covers purpose, usage, return content, and alternatives. It is complete enough for an agent to confidently 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?

The schema already documents all parameters with 100% coverage, but the description adds cross-parameter semantics ('All parameters are optional' and 'call with no arguments to browse latest listings'), which is not present in the schema. This justifies a score above the baseline 3.

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 uses a specific verb ('Search') and resource ('classified ads on Joomil.ch'), and clearly differentiates from siblings by explicitly directing users to get_classified for full details. It also mentions the marketplace context, 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?

It explicitly states that all parameters are optional and encourages no-argument calls for browsing. It names the sibling tool get_classified as an alternative for fetching full details, providing clear when-to-use guidance.

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

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

With annotations already declaring readOnlyHint=true and destructiveHint=false, the description adds useful behavioral context: it returns a 'ready-to-use filters object, a category confidence score and warnings for uncertain matches.' This goes beyond simple read/write safety and helps the agent understand the output nature.

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: three sentences each serve a purpose (what it does, when to use, what it returns). It is front-loaded and avoids redundant or filler content.

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 an output schema, the description is comprehensive. It covers the purpose, usage context, and expected output, making it sufficient for an agent to select and invoke the tool correctly without additional info.

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 already provides full coverage (100%) with a descriptive parameter explanation and examples. The description adds no additional parameter-level semantics beyond what the schema provides, so the baseline 3 is appropriate.

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 function with a specific verb and resource: 'Infer search_classifieds filters from a natural-language query.' It distinguishes itself from sibling tools by positioning as a pre-processing step for search_classifieds, not a direct search or retrieval 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 explicitly states when to use the tool: 'Use this before search_classifieds when the user mentions a category, location, canton or price in free text.' It provides clear context for usage, though it does not explicitly state when not to use it or mention alternative tools.

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