willys-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.0.0
Disambiguation4/5
The tools span distinct domains (stores, products, cart, orders, planning) with clear purposes. Some pairs like find_stores vs nearest_stores and search vs find_cheapest could be confused, but descriptions clarify the specific use cases. Overall, a capable agent can differentiate most tools without difficulty.
Naming Consistency4/5
Most tools follow a willys_verb_noun pattern (e.g., willys_get_cart, willys_plan_apply) with snake_case throughout. Minor deviations like willys_search, willys_login, and willys_setup_init don't break the pattern significantly. The naming is predictable and readable.
Tool Count3/5
With 31 tools, the server feels heavy, especially when including meta-tools like willys_fetch_url and willys_open_file that aren't grocery-specific. The broad scope (stores, products, cart, orders, planning, auth, setup) justifies many tools, but 31 is above the typical well-scoped range. It's borderline acceptable.
Completeness4/5
The tool surface covers the main workflows: store lookup, product search, cart management, order history, customer info, and meal planning. Missing explicit cart quantity updates or recipe listing can be worked around via add/remove and plan status. Overall, no critical dead ends for the core domain.
Average 3.5/5 across 31 of 31 tools scored. Lowest: 2.1/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 29 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It simply restates the tool's name without adding side effects, such as session invalidation or authentication requirements. No additional behavioral context is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short and under-specified, conveying little more than the tool name. While it is concise, it lacks essential information, making it insufficient rather than appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even for a simple logout tool, the description is incomplete. It fails to explain the sessionId parameter, the effect of the operation, or any prerequisites, leaving the agent without necessary context to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema lists a single required parameter (sessionId) with no description, and the description does not mention it at all. With 0% schema coverage and no compensatory explanation, the parameter's meaning and source are entirely undocumented.
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 'Avsluta sessionen.' (End the session) clearly states the tool's purpose as logging out, with a specific verb and resource. It distinguishes itself from sibling tools like willys_login and willys_check_auth by indicating session termination.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool, nor does it mention alternatives or prerequisites. It is implied that it is used to end a session, but no context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. 'Hämta' (retrieve) implies a read operation, but the description does not mention required authentication, return format, rate limits, or whether the profile data is cached or real-time. This is minimal disclosure for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short—a single phrase. While it avoids verbosity, it is under-specified and omits critical operational details. This is not conciseness but incomplete specification, similar to a placeholder.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations, output schema, and parameter documentation, the one-line description is wholly inadequate. An agent has no information about return values, required authentication state, error conditions, or how to construct the sessionId. The tool is not usable based on this definition alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter, 'sessionId', with zero description in the schema (0% coverage). The description does not mention this parameter at all, leaving the agent to guess what sessionId means, how to obtain it, and its role in retrieving customer info. There is no compensation for the schema gap.
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 'Hämta kundprofil' (Retrieve customer profile) clearly states a specific action and resource, directly reflecting the tool name 'willys_get_customer_info'. It is unambiguous, though it doesn't differentiate from sibling tools as there are no other customer-profile getters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives, such as willys_check_auth or willys_login. The only hint is the tool name itself, which implies usage but does not explain context, prerequisites, or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It states it gets history (implying read-only) but does not describe authentication requirements, pagination behavior, return format, or error scenarios. The sessionId parameter is only visible in the schema, not the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, which is concise, but the ambiguous 'sidad' and lack of any structure (e.g., sentences, usage hints) make it insufficient. It is under-specified rather than efficiently worded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool requires authentication (sessionId) and supports pagination (limit/offset), the description is incomplete. It does not explain how to use pagination or what to expect in the response, and there is no output schema to fill the gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does not explain sessionId, limit, or offset. Parameter names give some hint, but no additional meaning is added beyond the raw schema fields.
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 'Hämta orderhistorik' clearly states the tool retrieves order history, which is a specific verb+resource. It is distinguishable from sibling 'willys_get_order_details' by the plural 'orders' vs singular 'order', though the trailing 'sidad' is unclear and does not aid clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention differences from siblings like 'willys_get_order_details' or any context for ordering/pagination.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral disclosure. It does specify the exact content ('alla varurader' = all product rows) which adds value, but it does not mention session/auth requirements, side effects, or error behavior, leaving gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence and is front-loaded, but it is under-specified. It earns its place in terms of brevity, yet the extreme brevity sacrifices necessary context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with two string parameters and no output schema, the description should at least clarify that orderId likely comes from willys_get_orders and that a valid sessionId is required. This is absent, making the tool's context incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain what orderId or sessionId mean or how they are used. The only indirect reference is to 'a previous order', but the parameters are otherwise undocumented.
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 states that the tool returns all product rows from a previous order, which clearly identifies the data scope. It distinguishes from list-order tools by focusing on order items, though it lacks an explicit verb like 'get' or 'retrieve'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like willys_get_orders, nor any prerequisites such as obtaining an orderId from a prior call. The implied usage is retrieving details for a known prior order, but this is not made explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It simply states the action without revealing side effects, authentication requirements, idempotency, or potential errors. This is insufficient for a mutating tool.
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 a single, front-loaded sentence with no wasted words. It is concise, but the brevity contributes to under-specification, preventing a higher score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and output schema, the description is severely under-specified. It does not mention authentication, side effects on the cart, required session state, or return values, making it incomplete for a tool with 3 parameters and no structured data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the parameters (sessionId, productCode, quantity). The agent must rely solely on parameter names and types, which is inadequate for understanding required formats, relationships, or defaults.
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?
The description 'Lägg en produkt i kundvagnen' (Add a product to the cart) clearly states the action with a specific verb and resource. It distinguishes itself from sibling tools like remove_from_cart and get_cart by explicitly indicating the add-to-cart operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, context, or exclusions, leaving the agent without decision support for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. However, it only states the action without revealing whether the operation is read-only, requires special permissions, or has any side effects. The implicit read nature of 'get' is too minimal to qualify as transparent.
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 a single, concise sentence with no redundant words. It is front-loaded with the action and resource. However, it is so brief that it borders on under-specification, though it does not commit the tautology seen in poorly written descriptions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, no annotations, and one parameter, yet the description does not explain what the tool returns or what constitutes cart content. Given that the description is the sole source of context, it is incomplete and leaves the agent without essential information about the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a single sessionId parameter, and schema description coverage is 0%. The description does not mention this parameter or explain its purpose, leaving the agent to infer that it is a session identifier. The description fails to compensate for the lack of schema documentation.
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?
The description clearly states the tool's action ('Hämta' – retrieve) and resource ('kundvagnens innehåll' – cart contents). This distinguishes it from sibling tools like willys_add_to_cart and willys_remove_from_cart, which perform different operations on the same resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, such as requiring an authenticated session, nor does it explain why one would use this instead of willys_get_orders or similar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It indicates a refresh operation but does not disclose side effects (e.g., whether it writes to local storage, requires authentication, or makes network calls). The term 'Hämta om' implies a potentially mutating action, but there is no explanation of what happens to existing data.
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 a single short sentence in Swedish, which is efficient and front-loaded. It earns its place by stating the action and the resource. However, it could add a brief note about usage context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero annotations and no output schema, the description is the only source of behavioral context. It is too thin to be complete: it does not explain the purpose of refreshing the store registry, prerequisites, or what the user should expect after calling it. For a tool with zero parameters, a short but more informative description would be expected.
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?
The input schema has zero parameters, and schema description coverage is reported as 100% (vacuously, since there are no parameters). The description does not need to explain parameters. The baseline 4 applies because there are no parameters to describe.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Hämta om butiksregistret från Willys' uses the verb 'Hämta om' (refresh/fetch again) with the resource 'butiksregistret' (store registry), giving a basic sense of purpose. It distinguishes from sibling 'willys_find_stores' by indicating a refresh of the store registry rather than searching, but it does not clearly specify whether this is a full replacement or an update of cached data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives like 'willys_find_stores' or 'willys_get_store'. It does not state conditions such as 'use after setup' or 'when store data is stale'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does clarify that onlySwedish filters on verified Swedish labeling, not brand, which is a useful behavioral nuance. However, it doesn't disclose authentication requirements, pagination behavior, side effects, or response structure. Overall, minimal behavioral disclosure beyond the parameter nuance.
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?
The description is extremely concise: two short sentences, with the main purpose first and a parameter clarification second. No wasted words, and it front-loads the essential purpose. It earns its place by being directly informative without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 parameters, no annotations, and no output schema. The description provides only a minimal overview and a single parameter clarification. It leaves critical gaps, such as what query and sessionId are for, how pagination works, and what onlyBuyable does. For an agent to use this tool effectively, significantly more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 17% (only onlySwedish has a description). The description adds a clarification for onlySwedish (labels vs brand), which slightly extends the schema. But the other five parameters (query, sessionId, page, size, onlyBuyable) remain completely unexplained in both schema and description. The description does not compensate for the low coverage.
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 uses a specific verb 'Sök' and resource 'produkter', clearly indicating this is a product search tool. It distinguishes from siblings like willys_search_suggestions and willys_find_cheapest by focusing on general product search. However, it doesn't elaborate on search scope or result format, so it's not a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like willys_search_suggestions or willys_find_cheapest. The only extra info is about the onlySwedish parameter, which is a parameter clarification, not tool-selection guidance. There's no explicit 'use for X, not for Y'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the output is detailed product information and gives no insight into session/auth requirements, error behavior, response format, or side effects. The sessionId parameter is only visible in the schema, not explained.
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 a single concise sentence with no filler, front-loading the core purpose. It loses one point because it omits necessary context, but it is appropriately short and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema and no annotations, this description is too sparse for an agent to understand what product details are returned, why sessionId is needed, or how this tool relates to siblings. It covers only the basic purpose and one parameter, leaving significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only clarifies that 'artikelkod' corresponds to productCode. It does not explain sessionId at all, nor does it provide any format or constraint details beyond the schema's type declarations. The description adds minimal semantic value.
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 'Detaljerad produktinformation för en artikelkod' clearly communicates that the tool returns detailed product information for an article code, which distinguishes it from sibling tools like search or order details. It lacks an explicit verb, but the tool name supplies that, and the resource and scope are clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that the tool should be used when an article code is known and detailed product information is needed, which provides a basic usage context. However, it does not explicitly mention alternatives or when not to use it, such as when using willys_search for broad queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, leaving the description as the sole source of behavioral disclosure. It only mentions store-specific scope and replacement status; it does not cover authentication, return format, side effects, or pagination behavior.
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 extremely concise, with a single line that front-loads the core purpose and a second sentence for the migration note. It is not structured with sections, but the brevity is appropriate for a simple getter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, annotations, and sparse parameter coverage, the description is insufficiently complete. It omits expected return values, pagination mechanics, session requirements, and any prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% (storeId), and the description adds no parameter-specific details. It does not explain how page, size, or sessionId should be used, or how storeId relates to the 'store-specific' mention.
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 identifies the resource as store-specific campaigns and offers, which clearly aligns with the tool name 'willys_get_campaigns'. It also distinguishes the tool from the obsolete get_offers, but stops short of an explicit verb like 'lists' or 'retrieves'.
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 explicitly states that this tool replaces the dead get_offers, giving a clear alternative to avoid. However, it does not discuss when to use this over other sibling tools like willys_search or willys_get_product_detail.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It fails to mention whether the operation is read-only, any required authentication, rate limits, or potential costs. The only extra context (not CMS data) is about data source, not behavior.
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?
The description is a single, front-loaded sentence that provides the core purpose without wordiness. Every phrase earns its place by clarifying the data source.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description is too sparse to be complete. It doesn't explain what the return value looks like, how to handle pagination (if any), or any operational caveats. The tool has 3 parameters, but only one is documented in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is only 33% (only scanOrders has a description). The tool description adds no parameter details, leaving limit and sessionId unexplained. This fails to compensate for the low schema coverage.
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 clearly states the tool returns the most frequently purchased goods ('Vanligast köpta varor') and specifies the data source (actual order history vs. CMS page). This makes the purpose unambiguous, though it doesn't explicitly differentiate from sibling tools like willys_get_orders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by contrasting order history with the CMS page, suggesting this tool is preferred when real purchase data is needed. However, it doesn't explicitly state when to use this tool versus alternatives or provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description must disclose behavior, but it only states the basic check. It omits what happens for invalid sessions, return format, or side effects. It implies a read-only operation but does not explicitly say so.
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?
A single, focused sentence with no redundant words. It efficiently conveys the core purpose without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description should explain expected output or error behavior, but it doesn't. It is too sparse for fully autonomous use, though the tool is simple and the one parameter is straightforward.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required parameter (sessionId) with no description, and schema description coverage is 0%. The description does not explain the parameter's origin, format, or how to obtain it. The parameter name is self-explanatory but no additional meaning is added.
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?
The description clearly states the tool's function: checking session validity. It uses a specific verb 'Kontrollera' and a distinct resource (session validity), setting it apart from sibling auth tools like login/logout.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool or how it relates to login/logout or other session-related tools. It does not mention prerequisites, alternatives, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it reads from a local cache of 254 stores, which is a meaningful behavioral trait given no annotations. However, it does not mention potential staleness of the cache, error conditions, or any side effects. This partial transparency warrants a middle score.
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?
The two-sentence description is efficiently front-loaded, with no filler. Every word contributes to the core purpose or the cache behavior.
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?
Given no output schema and no annotations, the description is quite sparse. It omits return format, pagination, and how limit interacts with results. The cache note adds context, but the overall completeness is limited.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers query and onlyClickAndCollect, but the 'limit' parameter lacks a description. The description only reiterates the query field and does not explain limit or the boolean's effect beyond the schema. With 67% coverage and no added semantic value, it falls short.
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 'Slå upp butiker på ort, namn eller postnummer' clearly specifies the verb (look up), resource (stores), and search criteria. It implicitly differentiates from siblings like willys_get_store (specific ID) and willys_nearest_stores (location-based), but does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as willys_search or willys_nearest_stores. The description only states what the tool does, not when to prefer it, so it fails to provide usage context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It lists return content but does not explicitly state that this is a read-only operation, nor does it mention any authentication requirements, rate limits, or error behavior. The 'get' in the name implies non-mutating, but the description itself lacks this confirmation.
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?
The description is a single sentence with no fluff or redundancy. It efficiently lists the key detail categories in a compact list, which is ideal for quick parsing. Every word earns its place.
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 simple one-parameter read tool, the description covers the main output content (hours, fees, shipping threshold, offers link). However, without annotations or an output schema, it could go further by explicitly confirming read-only behavior and potential error conditions. The description is adequate but not rich.
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?
With schema description coverage at 0%, the description must compensate, but it only indirectly clarifies storeId by stating the tool returns store details. The parameter name 'storeId' is self-explanatory, and the description adds no format or syntax details. Since it is a single obvious parameter, the baseline of 3 is appropriate.
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 clearly states the tool provides store details (opening hours, pickup fee, free shipping threshold, and link to offers). This is a specific resource with concrete content, though it uses a noun phrase ('Detaljer för en butik') rather than an explicit verb. It is distinguishable from siblings like willys_find_stores or willys_nearest_stores, but the distinction is not explicitly made.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as willys_find_stores or willys_nearest_stores. It only states what the tool returns, leaving the agent to infer usage context. No exclusions or alternative recommendations are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the action but does not disclose side effects, whether it is destructive, requires authentication, or how it handles missing products or invalid sessions.
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?
A single, focused sentence that efficiently states the tool's purpose. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is sufficient for a trivial read-only tool, but for a mutation with no annotations, it lacks critical context such as prerequisites, error conditions, or expected behavior. Simple operation but incomplete for safe autonomous use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention the parameters. While sessionId and productCode are self-explanatory from their names, the description adds no meaning beyond the schema, failing to compensate for the low coverage.
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?
The description uses a specific verb ('Ta bort' = remove) and resource ('kundvagnen' = cart), clearly distinguishing from siblings like willys_add_to_cart and willys_get_cart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage context or alternatives are mentioned. It does not say when to use this tool versus adding or viewing the cart, nor any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only adds 'sorted by distance,' which is a useful but minimal trait. It does not disclose whether this is a read-only operation, what the output contains, how errors occur, or any authentication/rate-limit considerations. This is insufficient for an agent to anticipate tool behavior.
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?
The description is a single, concise Swedish sentence that efficiently communicates the core function. There is no redundancy, and the structure is front-loaded with the essential information. For such a short description, it is optimally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no output schema, and no annotations, the one-sentence description is not enough. It does not explain the meaning of limit or onlyClickAndCollect, what the response looks like, or any preconditions. This is a minimal viable description but lacks the completeness needed for an agent to invoke the tool correctly in a variety of scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining parameters. It only hints that lat/lng represent a coordinate. The optional parameters limit and onlyClickAndCollect are not explained at all, leaving their purpose and defaults ambiguous. An agent would not know how to set these without external knowledge.
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?
The description clearly states it finds the nearest stores to a coordinate, sorted by distance. It uses specific language ('Närmaste butiker till en koordinat') that conveys a precise verb+resource and distinguishes it from siblings like willys_get_store (single store) or willys_find_stores (general store lookup) by focusing on coordinate-based proximity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool should be used when you have a coordinate and need nearby stores, but it does not explicitly state when to use it versus alternatives like willys_find_stores or willys_search. There is no mention of exclusions or preferred alternatives, leaving usage guidance implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states that the tool provides suggestions, but does not mention whether the operation is read-only, what the response format looks like, or whether a sessionId is required for authentication. The agent is left without crucial safety and behavior information.
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?
The description is a single, concise sentence with no extraneous words. It is front-loaded with the core purpose and is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, and the description is too sparse. It does not specify what the suggestions look like, how the response is structured, or why sessionId is required. An agent would struggle to know what to expect from invoking the tool and whether any prerequisites exist.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions 'term' in a general sense, indicating that it is the search term, but it does not explicitly map the parameter name 'term' or explain its format. More importantly, the 'sessionId' parameter is completely unexplained. With 0% schema description coverage, the description fails to compensate for the lack of parameter documentation.
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?
The description clearly states that the tool provides search suggestions (autocomplete) for a term. This distinguishes it from sibling tools like willys_search, which likely performs a full search, and willys_get_product_detail, which returns product details. The purpose is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended usage is implied by the phrase 'autocomplete for a term' – it is meant for scenarios like search-as-you-type. However, there is no explicit guidance on when to use this tool versus alternatives, nor any exclusions or conditions. The tool name and description suggest the use case, but the description does not articulate it clearly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the transparency burden. It discloses an important behavioral trait: only one ingredient is removed and the recipe's other rows remain unchanged. However, it does not mention side effects, reversibility, or what happens if the ingredient is not found, which are relevant for a destructive operation.
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?
The description is a single, concise sentence that front-loads the action ('Ta bort') and includes a clarifying example without extraneous words. It is well-structured and immediately readable.
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?
The tool is a mutation with no output schema and no annotations, so the description should cover the full context. It explains the core action and its scoping but leaves gaps regarding the 'plan' parameter, the return value or success indication, and error behavior. Given the tool's simplicity, it is minimally adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67%: 'plan' and 'query' have descriptions, but 'recipe' has none. The tool description does not clarify the format or role of the 'recipe' parameter, nor does it connect 'recipe' and 'plan' contextually. It adds essentially no parameter-level meaning beyond what the schema already provides.
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?
The description uses a specific verb ('Ta bort' = remove) and clearly identifies the resource ('ingrediens ur ett recept' = ingredient from a recipe). It scopes the action to exactly one ingredient and explicitly states that other rows are untouched, which distinguishes it from sibling tools like willys_plan_remove_recipe (removes entire recipe) and willys_plan_set_ingredient (modifies ingredients).
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?
The description provides a contextual example ('t.ex. en skafferivara användaren redan har hemma' = e.g. a pantry item the user already has at home), implying when to use the tool. However, it does not explicitly name alternatives or state when not to use it; the differentiation from sibling tools is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses the destructive action (resetting the plan) and a key behavioral boundary (the cart is preserved), which is valuable contextual safety information. However, it does not explicitly mention irreversibility or the confirm requirement, though the schema covers the latter.
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?
A single, front-loaded Swedish sentence immediately states the action, followed by a clarifying negation about the cart. No filler or repetition; it earns its place.
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 simple destructive reset operation, the description covers the core action and the most likely source of confusion (cart vs. plan). The schema supplies parameter details and the confirm requirement, so the missing return-value information is not a critical gap, though a note on irreversibility would make it fully complete.
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 coverage is 100% with detailed descriptions for both parameters, including the confirm enum constraint. The description adds no parameter-specific syntax or format beyond restating the cart-preservation effect already present in the confirm property description, so the baseline of 3 applies.
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?
The description uses the specific verb 'Nollställ' (reset) with the resource 'planen' (the plan), clearly identifying this as a plan-clearing operation. It also disambiguates from cart-related siblings by explicitly stating it does not empty the cart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage—clearing an entire plan—but does not explicitly state when to choose it over alternatives like plan_remove_recipe or cart tools. It provides a 'when not' signal by clarifying the cart remains intact, but lacks a direct comparison or alternative naming.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses file creation, permissions (600), and return value, but does not address edge cases such as overwriting an existing .env or failure handling. This is adequate but not fully transparent.
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?
The description is two concise sentences in Swedish, each adding meaningful information: what the tool does, the output, and the next step. No wasted words.
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 simple setup tool with one optional parameter and no output schema, the description is reasonably complete. It covers purpose, output, and next step, but could ideally mention if it overwrites an existing .env or any prerequisites beyond finding the store.
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?
The input schema already provides a detailed description for storeId, including lookup workflow and optional omission. The tool description adds no additional parameter semantics beyond that, so baseline 3 is appropriate.
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?
The description clearly states the tool creates a .env file, writes the store-ID, sets permissions to 600, and returns the file path. It also references willys_open_file as the next step, distinguishing it from sibling tools like willys_setup.
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?
The description gives clear usage context: use willys_find_stores first to get the store ID, then create the .env, and finally open it with willys_open_file. However, it does not explicitly say when not to use this tool or mention alternatives like willys_setup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It reveals the sorting mechanism, that ranking applies across the entire hit set, and highlights a concrete pitfall with category-less ranking. It does not disclose auth or output shape, but for a read-only search tool this is reasonably transparent.
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?
The description is two sentences with the main function front-loaded and the category caveat in the second sentence. Every part is informative, and there is no filler or redundancy.
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?
Given 11 parameters and no output schema, the description covers the core ranking behavior, the category mechanism, and a critical edge case. It does not describe the full return shape or all parameter interactions, but the schema covers many parameters, making the description reasonably complete for a search tool.
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 coverage is 64%, and the schema already provides rich descriptions for many parameters. The description adds meaningful context about categories and the ranking pitfall, but does not explain undocumented parameters like limit, query, or onlyBuyable. It adds some value beyond the schema but does not fully compensate for the remaining gaps.
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?
The description clearly states the tool searches and ranks by comparative price (kr/kg, kr/l, kr/st), distinguishing it from general sibling search tools like willys_search. It also notes it returns available categories, further specifying its unique behavior.
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?
The description provides clear usage context by explaining that categories can narrow results and explicitly warns that without a category, minced meat sauce may rank as minced meat. It does not explicitly name alternative tools, but the specialized search-and-rank purpose implies when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool opens a file in the user's editor, does not read content, and is intended for .env setup. This gives the agent a clear safety profile, though it omits error behavior or return values. For a simple action, this is adequate transparency.
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?
The description is concise and front-loaded with the core action, followed by usage context, rationale, and a limitation. Every sentence adds distinct value with no filler or repetition.
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 single-parameter tool with no output schema, the description covers what, when, why, and what it does not do. It lacks explicit return value or error handling details, but the use case is well-anchored to the setup flow, making it nearly complete. Minor gap prevents a 5.
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?
The schema already fully describes the path parameter, including its use for .env and its source from willys_setup. The description adds no new parameter semantics beyond reconfirming the path source. With 100% schema coverage, the baseline score of 3 is appropriate.
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?
The description clearly states "Öppna en lokal fil i användarens standardeditor" (open a local file in the user's default editor), establishing a specific verb and resource. It also distinguishes itself from siblings by explicitly noting "Läser inte innehållet" (does not read the content), differentiating it from tools like willys_read_doc.
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?
The description provides explicit usage context: use for opening .env during setup, with the path from willys_setup. It explains the necessity (chat clients don't make file paths clickable) and notes the tool does not read content, implying an alternative for reading. However, it does not name a specific alternative tool, so it stops short of full when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosure. It reveals key behaviors: only diffs are sent, dryRun defaults to true and shows changes without touching the cart, and setting dryRun=false modifies a real cart only after explicit approval. This is solid safety-critical information, though it doesn't mention potential side effects like item removal.
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?
The description is two sentences long, front-loaded with the purpose and then a critical safety detail. Every word adds value: the first sentence defines the operation, the second explains the dryRun default and mutation risk. No fluff.
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 tool with 6 parameters and no output schema, the description covers the essential operational context: sync behavior, diff-only approach, and the dryRun safety valve. It could explain the return shape in dryRun more explicitly, but it states that changes are shown, which suffices for an agent to invoke it.
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 coverage is 83%, so the baseline is 3. The description doesn't add much beyond the schema; it references the diff logic but doesn't elaborate on parameters like acceptMatch or acceptSurplus. However, the schema already documents those well, so this is acceptable.
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?
The description clearly states the tool's function: 'Synka kundvagnen mot planen' (sync the cart against the plan), with a specific verb and resource. It also distinguishes itself from siblings like willys_plan_status by emphasizing it sends only the difference, making its scope unambiguous.
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?
The description provides clear context for when to use the tool: to apply a plan to the cart, and it highlights the safe default of dryRun=true. While it doesn't explicitly name alternatives like willys_plan_status, the sync vs. status distinction is implied, and the guidance to use dryRun first (via default) is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses important behavioral details: the needs are recalculated and items only required by the removed recipe disappear from the suggested basket. This goes beyond a simple 'removes' statement, giving users a clear picture of side effects.
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?
The description is two sentences, front-loaded with the primary action, and includes a meaningful consequence. Every word earns its place; no redundancy.
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?
The tool is simple with two parameters fully documented in the schema. There is no output schema, but the description explains the behavioral outcome (recalculation and removal of exclusive items), making the tool's effect clear enough for an agent to invoke it correctly.
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?
The schema covers both parameters fully with descriptions ('Vilken plan behoven hör till' and 'Exakt receptnamn att ta bort'). The tool description does not add additional meaning beyond what the schema already provides, so the baseline of 3 is appropriate.
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?
The description clearly states the tool's function: 'Ta bort ett recept ur planen' (remove a recipe from the plan), using a specific verb and resource. It distinguishes itself from sibling tools like willys_plan_add_recipe and willys_plan_remove_ingredient by specifying it removes an entire recipe.
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?
The description clearly implies when to use this tool: whenever a recipe should be removed from the plan. It does not explicitly mention alternatives or exclusions, but the context is clear enough and there are no competing removal tools with similar semantics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It communicates that the tool modifies only one ingredient without affecting others ('utan att röra de andra') and can both add and correct. However, it does not mention error behavior, permissions, or what happens if the recipe does not exist, leaving some gaps for a mutation-only tool.
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?
The description is two sentences, front-loads the primary purpose, and then gives a concrete usage scenario. No filler or redundant information, making it highly efficient.
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?
Despite having no output schema or annotations, the combination of the focused description and the detailed input schema covers the main use case well. It explains what the tool does, when to use it, and the schema documents parameter semantics thoroughly. Missing details like return values and edge cases are not critical for this targeted update operation.
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?
The description itself adds no parameter-level detail, but the input schema already provides rich descriptions for most parameters, including the nested ingredient object fields (query, amount, mustContain, etc.). With top-level schema coverage at 50% and nested properties well described, the description's lack of param info is acceptable but not compensated beyond the baseline.
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?
The description clearly states 'Lägg till eller rätta EN ingrediens i ett recept' (add or correct one ingredient), giving a specific verb and resource. It also distinguishes itself from willys_plan_add_recipe by explicitly positioning it as a fix for a single mismatched row rather than resending the whole recipe.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Använd detta för att fixa en felmatchad rad (t.ex. skärpa mustContain) i stället för att skicka om hela receptet med willys_plan_add_recipe.' This clearly states when to use the tool and names the alternative tool, making the usage context unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It clearly discloses the tool is read-only and changes neither plan nor cart, which is a key safety guarantee. It also describes the informational output (products, costs, pending surplus choices). It doesn't cover auth requirements or error behavior, but for a read-only status tool this is adequate.
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?
Two sentences, front-loaded with the primary action, followed by a safety note and a sequencing instruction. Every sentence provides essential value with no filler. Excellent structure.
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?
Given the absence of an output schema, the description adequately covers return content (products, quantities, costs, pending choices), usage order, and side-effect safety. It doesn't address edge cases like missing plans or invalid sessions, but it provides sufficient context for a status tool with simple parameters.
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?
The input schema already covers 75% of parameters (plan, preferTight, acceptSurplus are described; sessionId is not). The description adds no direct parameter semantics beyond mentioning 'surplus choices' generally. With high schema coverage, the baseline is 3, and the description neither improves nor detracts significantly.
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?
The description uses the specific verb 'Visa' (show) and identifies the resource (the plan). It clearly enumerates what is displayed: required items, proposed product and quantity per item, cost, and pending surplus choices. It also differentiates from willys_plan_apply by explicitly saying 'Kör detta innan willys_plan_apply'.
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?
The description gives explicit sequencing guidance: 'Kör detta innan willys_plan_apply' (run before applying). It also states that it is read-only, implying it should be used to inspect state before mutation. However, it doesn't mention alternative read tools or when not to use it beyond this context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden. It discloses that no session is required and specifies that the tool outputs exact steps with full file paths when configuration is incomplete. The verb 'kontrollera' implies read-only behavior, but it does not explicitly state whether the tool modifies anything, leaving a minor gap. Overall, it offers useful behavioral context beyond the minimal schema.
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?
The description is three concise sentences in Swedish, each serving a purpose: the first states the main action and deliverable, the second gives a usage condition and authentication requirement, and the third points to documentation. There is no redundancy or filler, making it appropriately front-loaded and efficient.
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 zero-parameter setup-check tool, the description explains what happens when something is missing (exact steps and file path) but does not describe the output when the server is already configured. Since there is no output schema, the description should clarify the success case or overall return format. The pointer to read_doc with help/setup.md partially compensates, but the gap keeps it from being fully complete.
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?
The tool has zero parameters, so per the guidelines the baseline is 4. The description correctly omits parameter details since there are none to explain, and no additional semantics are needed.
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?
The description clearly states the tool's function: 'Kontrollera om servern är konfigurerad på den här datorn' (check if the server is configured on this computer) and provides exact steps if something is missing. It also distinguishes itself from siblings by specifying when to run it ('om willys_login svarar SETUP_REQUIRED'), making its unique role clear.
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?
The description explicitly says to run this tool first when willys_login responds with SETUP_REQUIRED, which is a concrete usage trigger. It also notes that no session is required, setting expectations for authentication. It does not explicitly compare to sibling setup_init, but the reference to read_doc with help/setup.md guides the user to further documentation, providing adequate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It discloses a key side effect: amounts are aggregated across recipes, so multiple recipes wanting eggs become one need. It also clearly states what the tool does NOT do (does not modify the cart). However, it does not mention auth requirements, return format, or error conditions, which keeps it from being fully transparent.
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?
Two sentences, front-loaded with the primary action, then aggregation behavior, then a clear alternative. No fluff or repetition; every sentence carries useful content.
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 tool with no output schema and no annotations, the description covers the core semantics well: what it adds, aggregation behavior, and separation from cart mutation. It lacks explicit return value info and a bit more context about plans, but overall it is sufficiently complete for an agent to invoke it correctly.
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 about 50%, and the description adds context for how ingredients behave (e.g., aggregation key is the query term). The rich descriptions for ingredient subfields are in the schema, but the top-level 'ingredients' property and 'sessionId' remain inadequately described. The description offers some value but does not fully compensate for the gap.
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?
The description opens with a specific verb and resource: 'Lägg ett recepts ingredienser i behovsregistret' (add a recipe's ingredients to the requirements register). It clearly distinguishes itself from cart-related siblings by stating 'Rör inte kundvagnen — kör willys_plan_apply för det' and from other plan tools by focusing on adding recipes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells the agent not to touch the cart and names the alternative tool (willys_plan_apply). It also provides actionable guidance on when to reuse a recipe name to replace instead of duplicate, and instructs scaling amounts to actual portions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the mechanism (via user's home IP), the benefits (bypasses blocks, cheaper), the fallback behavior, and automatic JS rendering. This goes beyond a simple fetch description and prepares the agent for expected behavior.
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 sentences, each adding value: purpose, when to use, fallback, and rendering behavior. Front-loaded with the core action, no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter tool, the description covers the purpose, output format, usage priority, fallback, and rendering behavior. It is clear what the tool does and what to expect in return, making it complete without an output schema.
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 reinforces the 'render' parameter's auto-escalation behavior, but overall adds limited new meaning beyond what the schema already provides.
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?
The description clearly states it fetches a webpage from the user's computer and returns structured data (JSON-LD) plus clean text. This is a specific verb+resource with a clear output, distinguishing it from sibling tools that are all grocery-related.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to run this FIRST when reading a URL, and to fall back to own browsing only if this fails. Also explains the advantages (bypasses blocks, cheaper), giving clear context for when to use this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses key behaviors: credentials are read server-side, sessions are cached for 24 hours, and force=true triggers a new login. It also hints at rate limiting via the schema, but the description itself proactively communicates the safety and reuse behavior, which is essential for the agent.
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?
The description is two sentences long, front-loaded with the core purpose, and every clause adds useful information. There is no redundancy or filler, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter and no output schema, the description covers all necessary aspects: what it does, safety implications, session reuse policy, and the force option. It is sufficiently complete for the agent to invoke the tool correctly and safely.
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?
The schema already covers the force parameter at 100%, so the baseline is 3. The description adds value by explaining the purpose of force=true in the context of session reuse and the rationale for using it sparingly (based on schema's rate-limiting note), enhancing the agent's understanding of when to set it.
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?
The description clearly states the tool's function: logging in to Willys and returning a sessionId. This distinguishes it from sibling tools like willys_check_auth (checks authentication) and willys_logout (ends session), 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool: it is safe to call because credentials are read from .env and never enter the agent's context. It also explains session reuse and the force parameter for new logins, though it does not explicitly mention alternatives like check_auth or logout.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral disclosure. It explicitly states the tool is deterministically limited to the docs/ folder, cannot read .env, sessions, or anything else on the computer, and is safe to call freely. This directly addresses security and side-effect concerns.
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?
The description is three sentences, front-loaded with the core purpose, and every sentence adds relevant information: what it reads, its safety constraints, and the available documents. No unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and no output schema, the description covers everything needed to invoke it correctly: the resource type, the exact paths, the safety boundary, and its role relative to other instructions. It is complete without needing to explain return format.
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?
The schema already documents the 'path' parameter with 100% coverage, but the description adds value by listing the exact available document paths (help/setup.md, help/security.md, etc.), giving the agent concrete valid values beyond the schema's generic 'relative to docs/' explanation.
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?
The description clearly states the tool reads a document that comes with the server (e.g., "help/setup.md"). It distinguishes itself from siblings by explicitly limiting scope to the server's docs/ folder and emphasizing it is safe to call freely, which sets it apart from tools like willys_fetch_url or willys_open_file.
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?
The description notes that the short instructions point here for details, implying this tool is used to retrieve expanded documentation when needed. It does not explicitly name alternatives or exclusions, but the context is clear enough: use this to read bundled docs, not for other file access.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![willys-mcp MCP server](https://glama.ai/mcp/servers/oscarthroedsson/willys-mcp/badges/card.svg)](https://glama.ai/mcp/servers/oscarthroedsson/willys-mcp)

Score Badge

Copy to your README.md:

[![willys-mcp MCP server](https://glama.ai/mcp/servers/oscarthroedsson/willys-mcp/badges/score.svg)](https://glama.ai/mcp/servers/oscarthroedsson/willys-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/oscarthroedsson/willys-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server