wafle MCP server

Server Quality Checklist

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

Latest release: v0.2.0
Disambiguation2/5
The tool set has multiple overlapping tools with unclear boundaries, such as wafle_orders_list vs wafle_checkout_orders_list, wafle_orders_refund vs wafle_checkout_order_refund, and wafle_stores_get vs wafle_stores_settings_get. While descriptions often clarify the differences, the naming alone is insufficient, and an agent could easily select the wrong tool, especially given the large number of similar-sounding options.
Naming Consistency4/5
The tools follow a consistent wafle_<domain>_<action> pattern with snake_case throughout, which is predictable. There are minor deviations in verb choice (list, get, fetch, query, search) but no style mixing, so the overall pattern is coherent and easy to follow.
Tool Count1/5
With 124 tools, this server is extremely over-scoped. The calibration guidelines indicate that any server with 50+ tools is an extreme mismatch, which applies here. The sheer number makes it unwieldy for an agent to navigate, even if each tool is individually well-described.
Completeness4/5
The server covers a broad range of e-commerce domains (products, orders, customers, coupons, pricing, shipping, gateways, domains, stores, agents, AI jobs, ads, analytics, system health) with detailed lifecycles for most entities. Minor gaps exist, such as no delete operations for products, stores, or domains, and no direct order item editing, but these do not significantly hinder the overall workflows.
Average 4.2/5 across 100 of 124 tools scored. Lowest: 3.2/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- Last stable release on May 12, 2026
- 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?
The description claims 'Idempotency-keyed by template+public_id+timestamp so retries don't double-send within the same minute,' which directly contradicts the annotation idempotentHint=false. This is a significant inconsistency that misleads the agent about replay safety. The default template addition does not remedy the contradiction.
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 concise, front-loaded sentences. The main action is stated first, followed by essential default and idempotency details. No fluff or redundant information.
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 description covers the core action, default template, and idempotency behavior, but with no output schema and minimal annotations, it omits response format, error conditions, or required permissions. The contradiction with idempotentHint also undermines completeness. It is minimally adequate but has clear gaps.
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 33% (only slug has a description). The description does not compensate by explaining order_id or template beyond repeating the default already present in the schema. It adds no new semantic meaning for the parameters, leaving the agent without guidance on the non-obvious order_id accepted types or template format.
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 action: 'Resend a transactional email tied to an order.' It uses a specific verb and resource, and the scope is distinct from sibling tools like wafle_checkout_order_get or wafle_abandoned_send_recovery. The default template mention adds specificity.
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 the tool's use case (resending order emails) and provides the default template context. However, it does not explicitly mention alternatives or exclusions, such as when not to use it (e.g., for abandoned carts). The idempotency note gives practical usage guidance but no comparative guidance.
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?
Aside from the idempotentHint annotation, the description adds no behavioral detail. It doesn't disclose partial update semantics, response format, or error behavior, which are especially important for a PATCH operation with no output schema.
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 sentence with no filler, making it concise. However, it is terse to the point of missing valuable contextual information, so it earns a 4 rather than a 5.
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 minimal annotations, the description leaves out return values, error conditions, and optional field behavior. For a tool with multiple optional parameters, this is incomplete contextual coverage.
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 only 20%, with only slug described. The description fails to clarify the meaning of label, value, active, or rule_id beyond the fact that rule_id targets the rule. It doesn't compensate for the sparse 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 states a specific action (patch) on a specific resource (pricing rule) identified by id, clearly distinguishing it from create, delete, and list operations among siblings. The verb 'patch' implies partial update, which is accurate.
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 for updating existing pricing rules but provides no explicit when-to-use guidance or alternatives. It does not mention that creation is handled by wafle_pricing_rules_create or listing by wafle_pricing_rules_list, leaving the context implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotation Contradiction: the annotations declare idempotentHint=false, yet the description states 'Idempotency-Key header is auto-set; safe to retry on transient errors,' which directly contradicts the non-idempotent hint. Per the rubric, this contradiction forces a score of 1. Beyond the contradiction, the description does add some useful context (retry safety, snake_case convention), but the contradiction dominates.
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?
Three concise sentences, front-loaded with purpose and usage, and no wasted words. The convention pointer and retry-safety note add genuine value without bloat.
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?
This is a complex create tool with 8 parameters and nested objects, no output schema, and low schema coverage. The description omits return value/response format, auth requirements, error behavior, and full parameter semantics. It provides useful usage context and retry safety, but not enough context for an agent to invoke it correctly in all cases.
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 only 38%, so the description needed to compensate, but it only gives a high-level structural hint ('items[]+payment_method+gateway_id') and points to an external docs file. It does not explain key parameters like customer, shipping, metadata, coupon_code, or value formats, leaving significant gaps in parameter understanding.
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 specific action ('Manually create an order') and resource, and distinguishes this tool from sibling order tools by positioning it as a manual/back-office operation. The explicit 'Use only for migrations or telephone sales' sharpens the purpose and prevents confusion with storefront-driven order flows.
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 gives explicit when-to-use guidance ('Use only for migrations or telephone sales') and an explicit when-not-to-use exclusion ('normal orders flow from the storefront'). This is clear enough for an agent to decide when this tool is appropriate, even without naming an alternative MCP tool.
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?
The annotation provides idempotentHint, but the description adds no additional behavioral context. It does not disclose permissions, reversibility, or side effects beyond what the schema already implies. The relationship to wafle_stores_update is API-related, not a behavioral trait.
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 that efficiently conveys purpose and relationship to a sibling tool. It contains no redundant wording and front-loads the core action.
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 update tool with one required nested object parameter and no output schema, the description together with the schema and annotations is minimally adequate. It lacks information about return behavior and prerequisites like store existence, but the context is sufficient for a straightforward mutation.
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 descriptions for both 'slug' and 'settings'. The description adds the concept of a 'settings subtree' and mentions merging, but this is already implied by the schema's 'Object of fields to merge.' No significant additional parameter meaning is provided.
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 updates the store's settings subtree, which is specific and distinguishes it from general store updates. It also references wafle_stores_update to clarify the current behavior, removing ambiguity about scope.
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 explains that this tool is operationally identical to wafle_stores_update today, implying either can be used currently, but it does not explicitly state when to prefer this tool over alternatives. It lacks a direct 'use this when...' statement or exclusions.
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?
Annotations already declare readOnlyHint and idempotentHint, so the description's read-only nature is covered. The description adds value by naming the specific metrics included in the stats, which is useful context beyond annotations. It does not disclose additional behavioral aspects like data freshness or pagination, but given the annotations, 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?
The description is a single sentence that is front-loaded with 'Aggregated stats for an agent' followed by a concise list of the metrics. Every word earns its place, with no redundancy or filler. It is optimally concise for the information conveyed.
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 tool's moderate complexity, the description is largely complete: it covers the resource, the metrics returned, and (with annotations) the safety profile. The absence of an output schema is mitigated by listing the return metrics. It does not specify details like time range or aggregation period, which could be relevant, but these are not essential for a basic stats 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?
The input schema has 100% parameter description coverage for both 'slug' and 'agent_slug', so the schema fully explains the parameters. The description does not add any parameter-specific meaning beyond what is already in the schema, aligning with the baseline score of 3 for high 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 identifies the resource as 'aggregated stats for an agent' and lists the specific metrics (total runs, success rate, total cost, top tool names), which distinguishes it from sibling tools like wafle_agents_get or wafle_agents_runs_list. However, it lacks an explicit action verb like 'Retrieve' or 'List', relying on the tool name to imply the operation, so it stops short of a perfect score.
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: use this tool when you need an agent's aggregate statistics. It does not explicitly state when to use it over alternatives such as wafle_agents_runs_list for raw runs or wafle_ai_usage for usage metrics, nor does it mention any exclusions. The guidance is present implicitly but not articulated.
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?
Annotations are empty, so the description carries the full burden. It does disclose the mutating nature ('Save... and apply them') and the specific write path for product_description, which adds value beyond the schema. However, it omits whether changes are reversible, what happens to the job status, and behavior for other job types.
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, approximately 30 words, with the primary action front-loaded. The second sentence adds one specific, useful detail without any redundant phrasing or filler.
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 mutation tool with empty annotations and no output schema, the description is too sparse. It covers only the product_description case, leaving unclear what happens for other AI job types, what the response contains, and what the id parameter semantically refers to. The core action is stated, but the operational edges are unexplored.
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 67% (slug and user_edits are described, id is not). The description adds meaning to user_edits by explaining it lands in data.descriptions.<lang> for product_description jobs. However, the id parameter remains undocumented in both the schema and the description, so the description doesn't fully compensate for the coverage 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 uses a specific verb phrase 'Save user edits... and apply them' with a clear resource (AI job's output). The concrete detail about product_description writing to data.descriptions.<lang> adds specificity beyond the name, clearly distinguishing it from sibling accept/reject/get/list tools.
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 when to use this tool (when saving edits to AI job output) but doesn't explicitly name alternatives like wafle_ai_jobs_accept or wafle_ai_jobs_reject, nor does it state when not to use it. The product_description example provides partial context for one scenario but no broader guidance.
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. It explains the intended benefits but does not disclose side effects, reversibility, permission requirements, or what happens to the job/output. Mutation tools need more behavioral disclosure.
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, and no wasted words. Very concise and well-structured.
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?
Adequate for a simple rejection action, but gaps remain: no explanation of id/slug relationship, no mention of the 'reason' parameter, and no post-conditions. The description covers the main intent but lacks depth.
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 33% (slug has a description; id and reason do not). The description adds no parameter explanation, leaving id and reason ambiguous. With low coverage, the description should compensate but doesn't.
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 action: 'Mark an AI job's output as rejected.' This is a specific verb and resource, and the name 'reject' distinguishes it from sibling tools like accept/edit/get.
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: 'Use to keep usage stats clean and to preserve learning signal for prompt tuning.' This explains when to use it, though it doesn't explicitly discuss alternatives or when not to use it.
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?
The annotations already declare readOnlyHint and idempotentHint, but the description adds meaningful context by enumerating the returned data categories (customer, items, totals, gateway info, status, shipment data, timeline reference). This goes beyond the structured annotations and helps the agent understand the tool's output.
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 states the action first and then lists the returned fields in a compact, readable list. No superfluous words or repetitive 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 simple get-by-id operation with readOnly and idempotent annotations, the description covers the primary behavior and key return fields. It does not mention error conditions, authorization requirements, or how it relates to sibling order tools, but these are not critical for such a straightforward 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?
Schema coverage is 50%: slug has a description, but order_id does not. The description implies that order_id is the identifier used to fetch a single order, providing some semantic value, but it does not elaborate on the id's format or any additional constraints, leaving order_id partially under-explained.
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 a clear action ('Fetch a single order by id') and the resource (order), making the purpose readily apparent. However, it does not distinguish itself from the sibling tool wafle_checkout_order_get, which likely serves a similar function, so it doesn't fully differentiate.
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 wafle_checkout_order_get, wafle_orders_list, or wafle_orders_timeline. The description only states what the tool does, leaving the agent to infer usage context from the name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description calls out a 'DESTRUCTIVE side effect' and lists provisioning side effects, but the annotations declare destructiveHint=false. This directly contradicts the annotation, which is a serious inconsistency. The word 'DESTRUCTIVE' is misleading because the listed side effects (API key, audit log, gateway slot) are additive, not destructive.
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 purpose, followed by a useful workflow and side-effect disclosure. Every sentence serves a purpose, and it avoids unnecessary verbosity.
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 provisioning tool with no output schema, the description covers the onboarding workflow, required fields, and side effects well. It lacks return-value details, but the workflow guidance and side-effect disclosure give the agent enough context to select and invoke the tool. The annotation contradiction slightly undermines trust, but completeness is still strong.
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 has 100% parameter description coverage, so the baseline is 3. The description adds minimal semantic value by highlighting the three required parameters and referencing catalog_mode versus manual mode in the workflow, but it does not provide additional detail beyond what the schema already documents.
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 brand new wafle store, distinguishing it from sibling tools like wafle_stores_update and wafle_stores_get. It also lists the required fields (slug, name, domain), making the purpose and scope immediately evident.
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 says to use this tool when onboarding a new client and gives a concrete post-create workflow, mentioning wafle_gateways_create and wafle_stores_settings_update, with a conditional alternative for product sync vs manual catalog. However, it does not explicitly state when not to use the tool or compare it directly to alternatives.
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?
Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds value by explicitly flagging 'DESTRUCTIVE' and instructing to 'confirm with the user.' This procedural safety step goes beyond just the annotation and gives contextual guidance on how to handle this destructive action.
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 main action and followed by a clear warning. Every word earns its place; there is zero fluff or repetition.
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?
This simple one-parameter destructive tool lacks an output schema, so the description carries the burden of explaining behavior. It covers the action and the destructive nature, but does not explain what happens to the current version, whether the rollback is reversible, or what the tool returns upon success. The given information is adequate but leaves notable 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?
With schema description coverage at 0%, the description must compensate for undocumented parameters. It only repeats the word 'component' from the schema, giving no details on what a component is, whether it's an ID or name, or how to identify the correct component. The minimum length constraint is not explained and there are no enums or examples.
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 ('roll back') and clearly identifies the resource ('a component') and target state ('previous deployed version'). This distinguishes it from sibling tools like wafle_system_release_deploy (which deploys forward) and wafle_system_versions_list (which lists versions).
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 gives no guidance on when to use this tool versus alternatives. It doesn't mention when not to roll back, prerequisites, or that wafle_system_release_deploy could be used for deploying instead. The only usage hint is the requirement to confirm with the user, which is more of a procedural warning than a usage guideline.
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?
Annotations already cover read-only and idempotent behavior, lowering the bar. The description adds context by itemizing the returned fields (input_payload, output_payload, tokens, cost, etc.), which helps set expectations. Yet it omits error behavior or scope constraints (e.g., jobs are per-store), so it only partially discloses behavioral traits.
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 short sentences that front-load the primary action and then list the key return fields. No filler or redundancy, 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?
With no output schema, the description helpfully lists the main response fields. However, it fails to clarify the relationship between the slug and id parameters (e.g., whether the id is scoped to the store) and does not mention what happens if the job is not found. For a simple get tool, it is adequate but has clear gaps.
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 50%: the 'slug' parameter has a helpful description, but 'id' lacks one. The description says 'by id' which reinforces the purpose of the id parameter but does not add new semantics beyond the schema. Since id is a simple integer and slug is already described, the description provides marginal added meaning.
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 fetches a single AI job by id, with a specific verb and resource. It also lists the exact fields returned, distinguishing it from siblings like wafle_ai_jobs_list (which lists multiple) and wafle_ai_jobs_accept/reject (which modify).
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?
Usage is implied: fetching by id suggests it should be used when a specific job ID is available and full details are needed. However, it does not explicitly state when to prefer this over wafle_ai_jobs_list or mention any exclusions, such as needing the job to belong to the given slug.
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?
Annotations already identify the tool as read-only and idempotent. The description adds context about the order_id format but does not disclose any additional behavioral traits such as return structure or error conditions. This is acceptable given the annotations, but no extra transparency 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no filler. The primary action is front-loaded, and the parameter clarification is useful.
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 description is sufficient for a simple fetch tool given the annotations and full schema coverage. It clearly identifies the resource and parameter flexibility. It lacks a note on return values or differentiation from sibling order tools, but these are not essential for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions. The description enriches the order_id parameter by explaining that it accepts a numeric primary key or a public id with a specific pattern and where to find it (order detail page), going beyond the schema's example.
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 action ('Fetch one order') and the resource ('wafle_orders'), making the tool's purpose unambiguous. It does not explicitly differentiate from similar siblings like wafle_orders_get, but the verb+resource is specific enough.
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 when a single order is needed and provides guidance on the order_id format. However, it does not explicitly state when to choose this tool over alternatives like wafle_checkout_orders_list or wafle_orders_get, nor does it mention any exclusions.
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?
The description adds valuable behavioral context beyond the annotations: 'Past usage history is preserved on orders.' This clarifies that deletion does not wipe order history, which is useful for a destructive operation. It does not contradict the idempotent or destructive hints.
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 exceptionally concise: two short sentences that each convey essential information. The first states the core action, and the second provides an important behavioral note. 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 delete tool with two parameters and no output schema, the description plus annotations cover the main concerns. The preservation note adds context that helps the agent anticipate side effects. However, the lack of parameter semantic explanation prevents a perfect score.
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 input schema covers 'slug' with a description, but 'coupon_id' lacks any description beyond its type. The tool description does not explain the meaning of 'coupon_id' or its relationship to the slug. Since schema coverage is only 50% and the description does not compensate, this is a significant 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 clearly states the action ('Delete a coupon by id') with a specific verb and resource. It distinguishes itself from sibling tools like wafle_coupons_create, wafle_coupons_list, and wafle_coupons_update by indicating a delete 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?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or scenarios where this tool is appropriate or inappropriate, aside from the implicit fact that it deletes coupons.
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?
Annotations include idempotentHint: true, but the description adds important context: setting a gateway inactive will reject new charges while not affecting in-flight transactions. This warns about destructive consequences beyond what annotations convey. No contradiction with annotations.
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 purpose, followed by usage and a caveat. Every sentence earns its place, no redundancy, and it is well-structured.
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 tool with 6 parameters and no output schema, the description covers the core use cases and a destructive edge case, but lacks details on other parameters, return value, and error handling. It is adequate but not thorough.
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 has 6 parameters with zero descriptions. The description explains `creds` and `active`, which is helpful, but leaves `meta`, `name`, `description`, and `gateway_id` without explanation. `meta` is particularly ambiguous. With 0% schema coverage, the description should compensate more thoroughly for all parameters.
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 'Patch an existing gateway' – a specific verb and resource. It also gives concrete use cases (rotating credentials, toggling active), making the purpose clear. It doesn't explicitly distinguish from sibling gateway tools, but the verb 'patch' implies modification compared to create/delete/list/test.
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?
Provides explicit guidance on when to use: 'Use to rotate credentials (creds) or toggle active.' This gives clear context and intended scenarios. It doesn't mention when not to use or alternatives, but the use cases are specific enough for an agent to decide.
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 readOnlyHint and idempotentHint annotations already covering safety, the description adds value by disclosing the return content: each card includes an action field that is a writer call, plus confidence, expected_impact, and severity. It also explains the data semantics (server-side truth vs Meta attribution), giving the agent insight beyond the raw read-only nature.
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 four sentences long and front-loaded with the core purpose. Each sentence earns its place: the cross-tab explanation gives context, the card field enumeration substitutes for an output schema, and the apply reference guides next steps. It is slightly more verbose than a minimal two-sentence version but still efficient and well-structured.
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 read-only list tool with no output schema, the description is largely complete: it enumerates the card fields, explains the source of the recommendations, and points to the apply tool. Combined with the schema's parameter metadata (defaults, enums) and annotations, the agent has sufficient context to invoke and understand results, though extra details like pagination behavior are not mentioned.
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 only 40% (slug and status have descriptions), leaving page, per_page, and severity undocumented. The description does not compensate for these gaps—it never mentions the parameter usage, defaults, or filtering options. The only hint is the status schema description which is already in the schema, so the tool description adds little to parameter understanding.
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+resource: "List ads recommendations generated by wafle's AI engine," which clearly states the tool's function. It further distinguishes from siblings by explaining the recommendation content and explicitly referencing `wafle_ads_recommendation_apply` as the action tool, setting it apart from list-only and apply-only tools.
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 explaining what recommendations are and that applying them requires a separate tool, but it does not explicitly state when to use this over alternatives like `wafle_ads_anomalies_list` or `wafle_ads_performance_summary`. There are no exclusions or when-not-to-use instructions, only a follow-up action hint.
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. It adds the useful behavioral note that slug and tenant_id are immutable, and lists fields affected. But it does not disclose key mutation behaviors: whether patch is partial/merge, return values, authorization needs, or status transition rules. This is a moderate gap for an update 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?
Two tight sentences: the first states the action with a useful example list, the second adds a key constraint. No filler, front-loaded, and each sentence earns its place.
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 complex tool with nested objects, no output schema, and empty annotations, the description is under-specified. It fails to explain PATCH merge semantics (e.g., whether tools_allowed is replaced entirely), return structure, error scenarios, or constraints on status/trigger_config values. The agent may struggle to construct a correct patch payload and interpret the response.
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 67% (top-level params: slug and agent_slug have descriptions; patch does not). The description adds semantics for some patch subfields (system_prompt, tools_allowed, guardrails, etc.) but omits others (name, max_turns, temperature, trigger_type, tools_disallowed). It also confusingly references 'tenant_id' which is not an actual parameter, and does not clarify that slug/agent_slug are the immutable identifiers.
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 'Patch' with the resource 'existing agent', immediately distinguishing it from create/get/list operations. It lists key editable fields (system_prompt, tools_allowed, guardrails, trigger_config, model, status) and notes that identifiers are immutable, which further clarifies scope.
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 phrase 'Patch an existing agent' clearly implies usage for modifications rather than creation or retrieval. The list of changeable fields provides context for what use cases apply. However, it does not explicitly name alternatives (e.g., 'use wafle_agents_create for new agents') or state when not to use it.
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?
Since annotations are empty, the description must disclose behavior. It reveals that the output goes into a job and references a 24h TTL for caching, indicating an asynchronous or deferred workflow. However, it doesn't mention whether the operation is read-only, consumes AI credits, or what happens with the job if not accepted. Some behavioral context is added, but significant gaps remain.
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 no redundancy. It front-loads the main purpose and output format, then succinctly notes the job interaction and follow-up tool. 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?
Given there is no output schema, the description should explain return values or behavior. It mentions output goes into a job but doesn't say what the tool returns to the caller (if anything) or how to handle the job. It also omits edge cases like no approved reviews. The description provides a reasonable overview but lacks critical completion.
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 covers two of three parameters (sku and slug) with descriptions, but max_reviews lacks a description. The tool description does not add any parameter-level details beyond the schema, and it fails to explain the purpose or constraints of max_reviews. With 67% schema coverage, the description should compensate but doesn't.
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 what the tool does: 'Summarize the approved reviews of a product into 2–3 sentences plus sentiment + key points.' This includes a specific verb ('summarize'), resource ('reviews of a product'), and output format, distinguishing it from sibling tools like wafle_ai_product_describe or wafle_ai_categorize.
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 the workflow: the summary output goes into a job and requires calling wafle_ai_jobs_accept to cache it. This implies when to use the tool and the necessary follow-up, though it doesn't explicitly contrast with alternatives. The distinct purpose and reference to the accept step give adequate usage guidance without exclusions.
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. It discloses key behavioral traits (PII redaction and LLM usage), but does not specify side effects, permissions, or whether it modifies any data. This leaves some ambiguity about safety and consequences.
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 main purpose and followed by a relevant privacy detail. Every word earns its place, with no unnecessary filler.
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?
There is no output schema, so the description should explain the return value. It implies a drafted response but doesn't explicitly state the output format. The optional parameters are not explained, which is a notable gap for a tool with 5 parameters.
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 only 20% (only slug has a description). The description clarifies that inbound_message is the message to process and mentions redaction of emails/phones, but parameters like total_orders and last_orders_summary remain unexplained, leaving the agent without sufficient guidance.
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 as a customer-service co-pilot with specific verbs: classify, gauge sentiment, decide escalation, and draft a response. It identifies the resource (inbound message) and distinguishes from sibling AI tools like wafle_ai_categorize and wafle_ai_product_describe.
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—for customer-service inbound messages—but does not explicitly mention alternatives or when not to use it. The implied usage is strong enough for most cases.
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?
The description discloses a key behavioral trait: 'Only sent fields change,' which explains that unspecified fields remain unchanged. This goes beyond the idempotentHint annotation, which only indicates retry safety, by clarifying merge semantics. No contradiction with annotations exists.
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 short sentences, front-loaded with the core action and followed by a precise behavioral note. Every word earns its place, with zero redundancy.
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 patch operation with six parameters and no output schema, the description is adequate but minimal. It does not mention the return value, error conditions, or the role of required parameters (slug, coupon_id), though the schema lists required fields. The idempotent annotation provides some context, but additional details about expected outcomes or permissions would improve completeness.
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 only 17% (only slug has a description), so the description must compensate for the other parameters. It does not explain semantics for value, active, max_uses, or expires_at beyond their types and constraints, and only vaguely refers to 'by id' without explicitly mapping to coupon_id. Thus the description adds minimal value over the schema.
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 action (Patch) and the resource (a coupon by id), with the additional clarification 'Only sent fields change' indicating partial update semantics. This distinguishes it from sibling tools like create, delete, and list, leaving no ambiguity about what the tool does.
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?
Usage is implied: you would use this tool to update an existing coupon by its id. However, there is no explicit mention of when to use it over alternatives (e.g., create for new coupons, delete for removal) or any exclusions. The partial-update nuance provides some context, but lacks clear 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?
Annotations already declare readOnlyHint and idempotentHint, covering safety. The description adds useful behavioral context by specifying that email/phone are hashed and that output uses Google's expected column names. This goes beyond the annotations, though it does not describe pagination or output format details.
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 immediately communicates the tool's purpose and formatting specifics. Every word adds value without redundancy.
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 description covers the core purpose and key formatting details, but it omits information about the optional parameters, return format, and any prerequisites or constraints. For a relatively simple export tool with no output schema, this is adequate but not fully 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 only 33%, with segment and since_ts lacking descriptions. The tool description does not explain these optional parameters or how they affect the export. It only indirectly relates via 'audience' but fails to compensate for the missing parameter semantics.
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 exports an audience formatted for Google Ads Customer Match, specifically mentioning hashed email/phone and Google-expected column names. This distinguishes it from sibling export tools like wafle_exports_customers and wafle_exports_meta_audience by naming the target platform and format.
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?
Usage context is implied through the Google Ads Customer Match mention, but there is no explicit guidance on when to choose this tool over alternatives such as wafle_exports_meta_audience. No when-not-to-use or alternative tool names are provided.
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?
The annotation already provides destructiveHint=true, and the description adds 'Irreversible' and 'confirm before calling,' which reinforces permanence and adds an actionable safeguard. This provides context beyond the annotation without contradicting it.
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 short sentences, with the action front-loaded and the critical warning in the second sentence. No waste.
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 delete tool with annotations and two parameters, this is mostly adequate, but it lacks details like expected return values, behavior if the rule does not exist, and the role of the slug parameter in scoping. The presence of idempotentHint and destructiveHint helps, but the description itself could include a note that deletion is scoped by store slug.
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 says 'by id' but does not explicitly map which parameter (rule_id) is the identifier; the schema only describes slug, leaving rule_id without description. Since the description adds no additional meaning beyond the schema, it fails to compensate for the undocumented rule_id parameter.
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 'Delete' with the resource 'pricing rule by id', making the tool's purpose immediately obvious. The name and sibling tools (create/update/list) further distinguish it as the delete operation.
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 warns 'Irreversible — confirm before calling,' which is a relevant usage caution, but it does not explicitly state when to prefer this tool over alternatives like update or list. There is no guidance about prerequisites or using list to find rule IDs first.
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?
Annotations already declare readOnlyHint=true, and the description adds value by disclosing the return content (full conversation + audit log with enumerated step types), which helps the agent anticipate the response. It does not contradict annotations; it complements them. Minor gaps like pagination or error behavior are not critical for a read-only getter.
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, well-structured sentence that front-loads the verb-resource pair and then pads with a precise enumeration of step types. Every part is informative with no fluff, achieving high information density in minimal space.
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 read-only getter with two parameters, the description sufficiently covers resource, scope, and return content. Since there is no output schema, enumerating the step types helps complete the picture. It does not cover error conditions or preconditions, but those are less crucial for this tool given the readOnlyHint and simple parameter set.
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 does not add any meaning to the parameters beyond the schema. Schema coverage is 50% with slug described but run_id lacking explanation; the description neither describes run_id nor clarifies the relationship between slug and run_id. Parameter names are self-explanatory, but the description misses the opportunity to compensate for the missing run_id 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 a specific verb ('Get') and resource ('a specific run'), and specifies the scope ('specific run') which differentiates it from sibling tools like wafle_agents_runs_list. It also details the content ('full conversation + audit log') with the exact step types, leaving no ambiguity about what the tool does.
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 when one needs a specific run's full conversation/audit log, but it does not explicitly state when to use it instead of alternatives like wafle_agents_runs_list or mention any exclusions. Sibling tool names provide context but the description itself lacks direct comparison.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds the 'single customer' scope and email-based identification, but does not disclose pagination behavior, sorting, or return structure. With annotations covering safety, this is adequate but not rich.
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?
One clear, front-loaded sentence. No filler or repetition. 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?
The tool has four parameters and no output schema. The description is sufficient for a simple list operation, but lacks details about pagination behavior or the structure of returned orders. Given annotations and schema, it is minimally adequate but not 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 75% with descriptions for page, slug, and per_page. The description only reinforces that email is the customer identifier, which adds minimal value beyond the schema. It does not explain how slug, page, and per_page interact.
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 'List the orders of a single customer (by email)' clearly states the verb, resource, and scope. It distinguishes from sibling tools like wafle_orders_list (which likely lists all orders) and wafle_customers_get (customer data).
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?
Implies usage when you have a customer email and need their order history. It does not explicitly mention alternatives or exclusions, but the 'single customer (by email)' context provides clear guidance. No exclusions given, so it falls short of a 5.
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?
Given the minimal annotations (idempotentHint=false, destructiveHint=false), the description adds valuable side-effect context: notes appear in the timeline and customer-visible notes also appear on the order detail page and trigger email. This goes beyond the annotations, though it omits failure modes and idempotency consequences.
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 that covers purpose and key side effects efficiently. The minor inaccuracy in parameter naming slightly reduces its quality, but overall it is well-structured and concise.
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 description covers the main action and side effects, but it lacks a clear mapping to the actual boolean parameter name and does not mention return values or error conditions. It is adequate for basic understanding but leaves gaps that could affect correct invocation.
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 references `customer=true` but the actual schema parameter is `customer_visible`, which is a misleading mismatch. It does clarify the effect of the flag, but the incorrect parameter name could lead to invocation errors. Other parameters (order_id, text) are not explained beyond the schema.
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: adding an internal or customer-visible note to an order, with specific side effects. This distinguishes it from sibling order tools like cancel, refund, or ship.
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 provides clear context on when to use the tool (whenever a note must be attached to an order) and explains the difference between internal and customer-visible notes. However, it does not explicitly exclude alternatives or mention prerequisites like the order existing.
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?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds useful context about pagination, filtering, and return fields, but does not disclose deeper behaviors like ordering, error cases, or rate limits.
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 compact and front-loaded: two sentences that state the action, scope, and return fields, followed by a concrete use case. Every sentence earns its place with no wasted words.
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 read-only list tool with strong annotations and high schema coverage, the description is complete: it explains purpose, scope, pagination/filtering, returned fields, and a practical use case. No output schema exists, but the description lists the key return fields.
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 83%, so most parameters already have descriptions. The description only generically mentions 'pagination + optional search/filter' and does not add syntax or meaning beyond what the schema provides.
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 and resource: 'List products of a single store' with pagination and optional search/filter. It clearly states what the tool does and lists return fields, but it does not explicitly contrast itself with sibling tools like wafle_products_search or wafle_products_get.
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 context: 'Use to browse catalog or to find a product id before editing/overriding.' This tells the agent when to use it, though it does not mention when not to use it or explicitly name alternatives.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds the default date range behavior ('defaults to last 30 days'), which is useful. However, it does not describe the exact return shape (e.g., whether cost is in cents, currency, or interval buckets), leaving some opacity.
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 deliver the core purpose, use case, and default behavior with no fluff. The key information is front-loaded and every word 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 read-only aggregate with two well-documented parameters and strong annotations, the description is sufficient. It covers what, when, and the default time window. A brief note on return format would push it to 5, but it's complete enough for typical invocation.
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%: both 'slug' and 'since' have clear descriptions. The description only repeats the default date behavior already present in the schema, adding no new parameter-level meaning beyond what's structured.
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 identifies the resource ('Token + cost aggregate for a store') and the time scope ('since a date'). It also distinguishes from sibling analytics tools by explicitly targeting AI usage data and mentioning the AI dashboard chart use case.
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 use context: 'Use for the AI dashboard chart and quota guidance.' It does not name alternative tools, but the specific use case is enough for an AI agent to select this over generic analytics tools.
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?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is established. The description adds behavioral context beyond that: it returns revenue and orders aggregated into time buckets, which tells the agent what kind of data to expect and how it is grouped. This is useful non-obvious behavior not captured by annotations or schema enums alone.
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 and front-loaded with the core purpose. The first sentence states exactly what the tool does; the second provides immediate usage examples. Every word earns its place, with no fluff or repetition.
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 read-only analytics tool with no output schema, the description covers the main purpose and usage well. However, it does not explain the meaning of from_ts/to_ts or how custom ranges work, and it does not specify return formatting (e.g., currency, timezone). This leaves some ambiguity for an agent trying to construct a precise call, especially when 'custom' range is used.
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 only 40% (2 of 5 params have descriptions). The description helps clarify the 'bucket' parameter by listing day/week/month, and implies the 'range' parameter via 'last 30d', but it does not mention from_ts/to_ts for custom ranges. These two timestamp parameters are undocumented in the schema and remain unexplained, leaving a significant gap in parameter semantics.
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 performs a time-series breakdown of analytics, specifically revenue and orders, bucketed by day/week/month. This distinguishes it from wafle_analytics_summary (which likely provides a single aggregate summary) and other sibling tools. The verb 'breakdown' plus the resource 'analytics' and the scope of bucket intervals makes the purpose explicit.
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 'Use for charts and compare last 30d to previous 30d workflows,' giving clear when-to-use guidance. It does not mention when not to use this tool or name alternative tools (e.g., wafle_analytics_summary), so it lacks the full when/when-not/alternatives structure that would earn a 5.
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?
Annotations already cover readOnly and idempotent behavior. The description adds the list of KPIs and the notion of a time window, but does not disclose additional behavioral traits such as pagination, response format, or handling of custom ranges. This provides some value beyond annotations but no significant extra detail.
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 with no fluff: the first front-loads the KPI list, the second gives direct usage guidance. Every sentence 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 read-only summary tool, the description covers purpose, KPIs, and usage context. The only noticeable gap is lack of explicit explanation for from_ts/to_ts, but the tool's simplicity and the schema's enum for 'range' keep this acceptable.
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 50%, covering slug and range but not from_ts/to_ts. The description mentions 'window' and KPIs, but does not explain how custom ranges map to from_ts/to_ts. It partially compensates but leaves a gap for the undocumented parameters.
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 specifically states it provides 'high-level KPIs for a store over a window' and enumerates specific metrics (orders, revenue, AOV, etc.), clearly indicating the tool's function. It also differentiates itself as the 'starting point' for store health questions, distinguishing it from more specialized sibling tools.
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 instructs to use this tool as the starting point for any 'how is store X doing?' question, providing clear when-to-use guidance. However, it does not mention when not to use it or name alternative tools, so it falls short of a 5.
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?
The description goes well beyond the destructiveHint annotation by explaining the exact effect (recorded on wafle_orders row), the gateway-side behavior (manual_refund:true metadata), and the current limitation (v2 integration). It also discloses the guardrail on >50% refunds, offering rich behavioral context for an 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 three sentences, front-loaded with the purpose, and every sentence contributes distinct information (behavior, guardrail, side effects, limitation). 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?
The description is quite thorough for a destructive tool without an output schema, covering core behavior, side effects, and a key limitation. It does not explicitly describe the return value or error cases, but it's a single gap in an otherwise informative description.
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 only 20%, so the description must compensate. It significantly clarifies amount_cents (omitted/0 = full refund, otherwise partial) and confirm (required for >50%). However, it leaves reason and order_id semantics unexplained, and slug already has a schema description, so the added value is partial.
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 'Refund a paid order' with a specific verb and resource, and it adds detail on full vs. partial refunds. However, it does not explicitly distinguish itself from sibling tools like wafle_orders_refund, which could confuse an agent about which refund tool to use.
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 provides clear conditional guidance: full vs. partial based on amount_cents, and the confirm:true requirement for large refunds. It doesn't address when to prefer this tool over wafle_orders_refund or other alternatives, so the tool-selection context is implied by the name rather than stated.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows it is a safe read. The description adds value by disclosing the return contents (lifetime value, order count, last seen, top SKUs), providing behavioral context beyond the annotations.
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, well-structured sentence that front-loads the core action and resource, followed by a concise list of return stats. Every word adds value with no redundancy or filler.
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 tool's simplicity (2 params, no output schema, read-only annotations), the description adequately covers what it does and what it returns. It lists the aggregated stats, which is sufficient for an agent to know the expected output, though it omits details like error conditions or response format.
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 50%: the slug parameter is well-described, while email has only a format. The description clarifies that email is the lookup key, but does not add detail for slug or further explain parameter meaning. It partially compensates for the email gap but remains moderate.
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 'Fetch a single customer profile by email', specifying the verb (fetch), resource (customer profile), and unique access method (by email). It also lists the returned stats, distinguishing it from sibling tools like wafle_customers_list and wafle_customers_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 for retrieving a specific customer, but it does not explicitly contrast with alternatives or provide when-to-use vs. when-not-to-use guidance. Sibling tools like wafle_customers_list exist, and the description does not mention when to choose this over them.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe, read-only operation. The description adds only the fact that segments are used in other contexts; it does not disclose additional behavioral traits such as response shape, pagination, or any limits. This is minimal beyond what annotations provide.
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 core purpose in the first sentence and an integration context in the second. Every word earns its place, no wasted 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 simple list tool with one fully described parameter and read-only annotations, the description is nearly complete. It explains what the tool returns (segments) and how they are used. The only minor gap is the lack of explicit response shape (e.g., whether it returns segment IDs or names), but since it's a list tool with no output schema, this is a small omission.
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% for the single `slug` parameter, which is fully described with format and example. The description itself doesn't add any further parameter semantics or syntax details, 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 'List' and clearly identifies the resource as 'customer segments configured for a store.' It also differentiates from siblings by noting these segments power the `segment=` filter in `wafle_customers_list` and audience exports, making its role distinct 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 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 stating that segments power the `segment=` filter in `wafle_customers_list` and audience exports, implying when to use the tool (when a list of segment values is needed). It doesn't explicitly state exclusions or alternatives, but the cross-reference to the sibling tool gives the agent effective 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?
Annotations already declare the tool read-only and idempotent. The description adds value by detailing what data is returned (SSL expiry, last renewal, log, DNS instructions) and notes the ability to re-show DNS-setup instructions, which is behavior beyond the basic read-only hint.
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 concise and front-loaded with the core function, followed by practical usage examples. Every sentence adds value, though the first paragraph could be slightly more compact.
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 read-only status tool, the description covers the output details and use cases well, especially given the lack of an output schema. However, it omits parameter relationship details and potential edge cases, which slightly reduces completeness.
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% (slug and include_log have descriptions), but the required id parameter has no description, and the tool description does not clarify how id and slug are used. This is a significant gap for selecting and invoking the tool correctly.
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 fetches the full status of a single attached domain, listing specific data points like status, SSL expiry, and renewal. This distinguishes it from sibling tools such as wafle_domains_list, wafle_domains_add, and wafle_domains_verify.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete use cases: answering 'is the domain working yet?' and debugging stuck verification. It does not explicitly state when not to use the tool or mention alternatives, but the context 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?
Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds behavioral detail by stating 'Wafle returns the raw CSV/JSON in the response body' and listing the exported fields. No contradiction exists, and the added response-body context is useful.
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 well-structured: two short sentences front-load the core purpose and response format, followed by usage guidance and a caveat. Every sentence adds value with no redundancy.
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 description sufficiently covers the export purpose, formats, included fields, and a performance caveat for large stores. However, given no output schema and low parameter coverage, it lacks detail on the segment and min_orders parameters and does not fully describe response edge cases, making it only partially 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 low (25%, only slug is documented). The description mentions the default format (CSV) but does not explain the segment or min_orders parameters, leaving their semantics unclear. With limited schema coverage, the description should compensate, but it fails to do so for most parameters.
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 'Export the customer list of a store as CSV (default) or JSON' and lists the included fields (email, name, phone, total spent, order count, last seen). This specific verb+resource+format combination effectively distinguishes it from sibling export tools like wafle_exports_google_ads and wafle_exports_meta_audience.
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 CRM imports or general data exports.' It also advises an alternative for large stores ('prefer the dashboard download flow'), though it does not mention sibling tool names directly.
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?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is known. The description adds valuable context beyond annotations: the auth requirement (owner/admin role) and the scope (includes pending invitations). This helps the agent understand the tool's behavior and prerequisites without contradicting the annotations.
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, highly concise, and front-loaded with the core action. The first sentence states the function, and the second provides the essential role requirement. No redundant or extraneous information is included.
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 list tool with one parameter and no output schema, the description covers purpose, scope, and auth requirement. It could optionally mention pagination or return format, but these are minor gaps given the straightforward nature of the operation. Overall, it provides sufficient context for an agent to select and invoke the 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?
The input schema has 100% coverage for the tenant_slug parameter (with example 'gamerland'), so the schema already provides full parameter meaning. The description does not add any additional parameter-level details, such as format or constraints. Baseline 3 is appropriate given schema 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 clearly states the tool's function: 'List all members of a tenant' with explicit inclusion of 'accepted memberships + pending invitations.' This specific verb-resource pairing distinguishes it from siblings like wafle_users_memberships_list (current user's memberships) and wafle_invitations_create (creating invitations).
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 specifying a tenant and role requirement ('Requires `owner` or `admin` role'), but it does not explicitly mention alternatives or when not to use it. For example, wafle_users_memberships_list could be an alternative for the user's own memberships, but no such exclusion is stated. Usage guidance is present but not fully 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?
Annotations already declare readOnlyHint and idempotentHint. The description adds a useful behavioral detail: the response includes meta.gatewayId and meta.gatewayType for correlating with payment status. This goes beyond the annotations without contradicting them.
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, each earning its place: what it does, when to use it, and a notable response field. No fluff, fully front-loaded.
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 list tool with strong annotations and schema, the description is fairly complete. It covers purpose, usage, and one important response aspect. It doesn't detail default ordering or response envelope, but those are not required given the schema and no 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 coverage is 75%, so baseline is 3. The description mentions filter categories (status, date range, customer email, search) but adds little beyond what the schema already provides. The 'search' parameter is undocumented in the schema and the description doesn't explain its semantics, so it doesn't fully compensate.
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 lists orders for a store with pagination and filters, using a specific verb and resource. It does not explicitly differentiate from the sibling wafle_checkout_orders_list, but the focus on store slug and filters is reasonably specific.
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 usage context: 'Use this for any 'pendientes', 'enviados', 'últimos N días' style query.' This tells the agent when to use it, though it doesn't mention alternatives or exclusion cases.
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?
The description adds behavior beyond annotations: it updates status to 'shipped' and triggers a customer notification email if the store has it enabled. This is useful context that complements the idempotentHint and destructiveHint annotations.
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 concise sentences, front-loaded with the main action. No redundant information; every sentence adds value.
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 mutation tool with annotations, the description covers the main behavior and side effects (email trigger). It lacks some detail about optional parameters and return values, but overall is sufficient for an agent to understand the tool's 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?
Schema coverage is only 33%, so the description must compensate. It mentions carrier and tracking_number, and indirectly notify_customer via the notification email behavior, but does not explain tracking_url or order_id. Partial compensation for low schema 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 clearly states the tool's purpose with a specific verb and resource: 'Mark an order as shipped.' It also details what happens (records carrier and tracking number, updates status) and differentiates from sibling tools like cancel or refund.
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 primary use case is implied by the verb 'ship', but there are no explicit when-to-use or when-not-to-use instructions, nor mention of alternative tools for different order actions (e.g., refund, cancel).
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to restate safety. It adds 'lightweight' and 'optimized for autocomplete' as performance context, but doesn't disclose return format, pagination, or other behavioral details, which is acceptable given the annotation coverage.
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 core function and then adds the comparative context with wafle_products_list. There is no redundant or filler 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 straightforward search tool with read-only annotations and schema coverage for most parameters, the description is sufficiently complete. It explains the tool's purpose, its relationship to a sibling, and the optimization context. The lack of output schema and return details is acceptable given the tool's simplicity.
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 provides descriptions for q and slug, leaving limit undocumented. The description doesn't add parameter-level meaning beyond the schema, and it doesn't compensate for the missing limit semantics. With 67% schema coverage, a 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 the tool performs a 'lightweight search of products by name/sku', with a specific verb and resource. It further distinguishes from sibling wafle_products_list by noting it's equivalent but optimized for autocomplete, leaving no ambiguity about its function.
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 names wafle_products_list as an alternative and indicates this tool is optimized for autocomplete, giving a clear use case. However, it doesn't explicitly state when not to use it or provide exclusions, stopping short of full guidance.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the tool is known to be a safe read. The description adds the list of possible statuses and pairing context, but does not disclose behavior for unknown/expired job IDs or error handling. This goes slightly beyond annotations but lacks richer behavioral detail.
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 containing the action, resource, status values, and pairing instruction. Every word earns its place with zero waste.
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 tool's simplicity (one parameter, no nested objects, no output schema), the description reasonably covers the return value by listing statuses. It does not address edge cases like job not found or expiration, but for a straightforward status-check tool with strong annotations, this is sufficient.
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%, and the parameter `job_id` is clearly described as the value returned by `wafle_products_sync_trigger`. The description adds no additional parameter syntax or semantics beyond the schema, 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 uses a specific verb ('Get') and clearly identifies the resource ('status of a product-sync job') with the possible statuses enumerated. It also distinguishes itself from the sibling trigger tool by explicitly mentioning pairing with `wafle_products_sync_trigger`, making its 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 explicit usage context by instructing to pair with `wafle_products_sync_trigger`, implying this tool is used after triggering a sync job. It doesn't discuss exclusions or alternatives (like `wafle_products_sync_trigger_and_wait`), but the clear pairing guidance is sufficient for correct usage.
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?
Annotations only note idempotentHint=false and destructiveHint=false. The description adds important behavioral context: the operation is asynchronous, returns a job id for polling, and behaves as a no-op error on manual stores. This goes beyond the minimal annotation data and discloses key runtime 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 two short paragraphs, with the core action and return value front-loaded. Every sentence contributes meaningful information: async trigger, polling instruction, and the catalog mode constraint. 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 trigger tool, the description covers the essential context: it returns a job id, tells the agent to poll the status endpoint, and warns about the manual-store edge case. Without an output schema, this is sufficient for an agent to select and invoke the tool 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 100%, with both `slug` and `mode` having informative descriptions. The tool description does not add additional parameter meaning beyond the schema, so 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.
Purpose4/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: 'Trigger an asynchronous catalog sync for a store.' It adds that it returns a job id and directs polling to a specific status tool. However, it does not explicitly differentiate from the sibling tool `wafle_products_sync_trigger_and_wait`, which is a closely related alternative.
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 conditions: it is 'only meaningful on catalog_mode = supabase_sync stores' and on manual stores it is a 'no-op error.' This gives clear when-to-use and when-not-to-use guidance. It does not mention alternatives such as `wafle_products_sync_trigger_and_wait`, but the provided context is strong.
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?
The description goes beyond the idempotentHint and destructiveHint annotations by explaining the idempotent behavior (re-applying returns previous result) and the queued behavior for human-judgment actions. This adds meaningful context about what happens when the tool is invoked, including the return value for queued actions.
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 well-structured. It front-loads the core action, then covers idempotency and the special queuing behavior in a second paragraph, without unnecessary words or repetition.
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?
Although the description covers the main behavior and the queuing special case, it lacks detail on the general return structure (only mentions ok=true for queued) and error conditions. Given there is no output schema, the description carries more responsibility and could be more complete, but it still provides essential behavioral context.
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 provides a description for 'slug' but not for 'recommendation_id'. The description clarifies that the id refers to the recommendation being applied, which adds some meaning, but it does not explain the slug parameter beyond what the schema already states. With 50% schema coverage, the description offers only partial compensation.
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 applies a wafle ads recommendation by id, runs the underlying writer action, and marks it as applied. It distinguishes this from direct actions like campaign pause by framing it as applying a recommendation, and the sibling list reinforces that distinction.
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: when you have a recommendation id and want to execute it. It also explains special handling for human-judgment actions, but it does not explicitly contrast with alternative tools like wafle_ads_campaign_pause or wafle_ads_campaign_update_budget, though the context makes the use case obvious.
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 behavioral disclosure. It explains the state transition to 'cancelled' and the side effect that the pending tool call is not executed, which is key context. It does not discuss reversibility, permissions, or error states, but the main outcome is clearly conveyed.
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 short sentences that front-load the purpose and consequence, with no filler or repetition of schema field names. Every word adds value.
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 action tool with no output schema and no annotations, the description covers purpose, precondition, and outcome well. It does not cover return behavior or edge cases, but the essential context is present.
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 only 33% (only 'slug' is described). The description does not explain 'run_id' or 'note' beyond saying 'a run', so it fails to compensate for the low coverage. The meaning of 'run_id' is only implied by the tool's purpose.
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 'Reject', identifies the resource as 'a run that is awaiting_approval', and states the outcome: 'Run goes to cancelled; the pending tool call is NOT executed.' This clearly differentiates it from sibling tools like wafle_agents_runs_approve.
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 a clear precondition ('a run that is awaiting_approval') and consequence ('goes to cancelled; the pending tool call is NOT executed'), indicating when to use the tool. However, it does not explicitly name alternative tools or provide exclusions, leaving some ambiguity for an agent choosing between approve/reject.
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 discloses concrete write behaviors: writing descriptions to catalog rows, category overrides to product rows, and caching reviews summaries. It also explains why other types have no side effect (translation already cached, segment_compile read-only). However, it doesn't mention job state changes, reversibility, or error handling.
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 compact and front-loaded with the main action, followed by a bulleted breakdown of job types and their side effects. Every sentence adds necessary information without 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 description covers the key complexity of varying behavior across job types and explicitly enumerates what gets written for each. It lacks details on job state transitions or return formats, but with no output schema, those are less critical. Overall, it gives sufficient context for an agent to decide when to use the tool.
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 does not explain any parameters. The schema provides a description for `slug` with an example but leaves `id` undescribed, and at 50% schema coverage, the description fails to compensate by clarifying that `id` is the AI job identifier. This is a significant gap for an agent selecting and invoking the tool.
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 'Apply an AI job's output to the platform' and enumerates specific job types with their write targets (catalog, product rows, reviews aggregates). This makes it distinct from siblings like wafle_ai_jobs_reject and wafle_ai_jobs_get.
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 explains when to use accept by listing the job types that have platform side effects (product_description, categorize, review_summary) and explicitly notes that other types have no side effect, implying they don't need acceptance. It doesn't explicitly name alternative tools like reject, but the job-type breakdown provides effective usage 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?
The description adds valuable behavioral context beyond the sparse annotations (idempotentHint=false, destructiveHint=false). It discloses case-insensitivity of codes, epoch-second date fields with 0 as no bound, and demonstrates type-specific semantics through examples. However, it does not cover all side effects or return behavior, so a full 5 is not warranted.
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 well-structured, front-loading the essential purpose and then providing bullet-point examples. Every sentence contributes value, making it easy to scan and understand.
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 12 parameters and no output schema, the description covers the most important usage patterns but omits several parameters (e.g., min_subtotal, stackable, max_uses) and does not describe the return value. It is sufficient for a simple create, but not fully complete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at only 25%, the description compensates by clarifying the key parameters through practical examples: how type, value, applies_to, and applies_to_ids interact. It also explains date field semantics. Yet not all parameters (e.g., min_subtotal, stackable, active) are addressed, leaving some ambiguity.
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 'Create a coupon' with a specific verb and resource, unambiguously distinguishing it from sibling tools like wafle_coupons_update, wafle_coupons_delete, and wafle_coupons_list. The purpose is immediately evident.
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?
Usage context is implied through the name and the common patterns, but there is no explicit guidance on when to use this tool versus alternatives (e.g., wafle_coupons_update for modifying existing coupons). The examples hint at usage scenarios but do not state exclusions or alternatives.
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?
Annotations already declare readOnlyHint and idempotentHint, covering safety. The description adds behavioral detail about the output format (hashed email + phone per row, schema-compatible with Meta CSV) and filter usage, which is helpful beyond structured annotations.
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 concise sentences front-load the purpose and include meaningful use-case context without repetition or filler.
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 description gives a solid overview of purpose and output format, but with no output schema and two undocumented parameters, it leaves the return type/delivery mechanism and the roles of since_ts/min_total_spent unspecified, making it only moderately 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 description coverage is 50%, and while the description enriches the 'segment' parameter by explaining its retargeting purpose, it does not provide meaning for 'since_ts' or 'min_total_spent', which lack schema descriptions. It partially compensates but leaves 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's function: exporting an audience formatted for Meta custom audiences with hashed email and phone, and mentions filtering by segment for retargeting cohorts. This distinguishes it from sibling exports like wafle_exports_google_ads and wafle_exports_customers.
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 conveys the intended use case: building retargeting audiences for Meta custom audiences by filtering segment. It provides clear context, though it does not explicitly name alternatives or exclusions.
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?
Annotations provide idempotentHint: false and destructiveHint: false, so the agent knows it is a non-idempotent, non-destructive operation. The description adds useful behavioral context about credential requirements and the follow-up test step, but does not disclose potential side effects (e.g., creation of an inactive gateway, behavior on duplicate names, or permission requirements). This is a gap for a create tool with no output 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 compact, front-loaded with the action, and uses a bullet list to convey type-specific requirements. Every sentence provides actionable information; the follow-up test instruction is valuable and not redundant.
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 8 parameters, nested objects, and no output schema, the description covers the type-specific fields well but omits what the tool returns (e.g., the created gateway object or ID). The guidance about testing is helpful, but the missing return-value information makes it incomplete for an agent that must handle the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 38%, so the description carries the burden for parameter meaning. It adds critical semantics by mapping each `type` to required `creds` and `meta` fields, which is not obvious from the schema alone. It does not explain `name`, `currency`, or `active` beyond schema defaults, but the schema already provides basic types and defaults for those.
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 'Create a new gateway', using a specific verb and resource, and the type list distinguishes it from siblings like wafle_gateways_delete, wafle_gateways_update, and wafle_gateways_test. The scope is immediately 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?
Provides clear context by listing provider-specific requirements and explicitly instructs to run wafle_gateways_test 'before pointing a store at it.' However, it does not explicitly mention when to prefer create over update or when creation should be avoided, though the sibling set makes this implicit.
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?
Annotations already indicate idempotent and non-destructive behavior. The description adds the owner role requirement and lists the updatable fields (role, scopes, is_active). It does not disclose side effects such as whether updating role resets scopes, but with annotations covering the safety profile, this is acceptable.
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 that front-loads the action, includes the target resource, and mentions the permission requirement. Every word is useful, with no redundancy or filler.
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 5-parameter update tool with no output schema, the description covers the action, permission requirement, and which fields can be updated. It does not specify return value or edge cases, but given the tool's simplicity, this is adequately 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.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover tenant_slug, user_id, and scopes, but role and is_active lack descriptions. The description only repeats the field names without explaining the role enum or is_active semantics. With 60% schema coverage, the description fails to compensate for the missing parameter explanations, adding minimal value beyond the schema.
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 'Update a member's role / scopes / is_active for a given tenant' with a specific verb (update) and resource (member). It is distinguishable from sibling tools like wafle_members_list which only lists members, and there is no other member update tool in the sibling list.
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 notes 'Requires `owner` role on the tenant', providing a clear precondition for use. It does not mention alternatives or exclusions, but given the sibling list, there is no comparable update tool, so the usage context is clear enough without further comparison.
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?
Annotations already declare readOnlyHint and idempotentHint, so the safe read-only nature is known. The description adds behavioral context by listing the types of events returned and indicating chronological ordering, which goes beyond the annotations. This is useful context without contradicting the annotations.
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 only two sentences, front-loaded with the purpose and followed by a clear usage note. Every word earns its place; there is no redundancy or filler.
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 tool's simplicity (2 required parameters, no output schema), the description covers the core purpose and use case. It mentions the types of events included, which gives a high-level view of the return content. It does not describe pagination or exact response structure, but with no output schema, the description carries more responsibility; still, it is adequately complete for an audit-focused read-only tool.
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 only 50%: the 'slug' parameter has a helpful description with examples, but 'order_id' has no description. The tool description does not elaborate on either parameter, particularly 'order_id', leaving the agent to infer its meaning from the name. With low schema coverage, the description should compensate but does not.
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 with a specific verb ('Get') and resource ('the chronological timeline of an order'), and enumerates the event types included (status changes, payment events, shipment, notes, refunds). This distinguishes it from sibling tools like wafle_orders_get by focusing on the timeline/history rather than current order state.
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 second sentence provides a clear usage context: 'Use to audit how an order got into its current state.' This explains when to use the tool, though it does not explicitly mention alternatives or when not to use it. That is a minor gap, so it falls short of a 5 but is still well-guided.
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?
Annotations already declare idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds that retries can be targeted by id or kind, which is useful, but does not disclose potential side effects like whether the job is removed from the failure queue or if there are rate limits. No contradiction with annotations; the baseline is met but no extra context beyond the annotations 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that captures both modes of operation without filler. It is front-loaded with the primary verb and object, making it immediately scannable.
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 tool with two optional parameters and no output schema, the description covers the main intent but omits critical details: what happens if neither parameter is set, whether the parameters are mutually exclusive, and what the response looks like. It is minimally viable but leaves gaps that could lead to incorrect invocation.
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 describes 'kind' but not 'job_id' (50% coverage). The description compensates by explaining that retrying 'by id' refers to job_id and 'all failed jobs of a kind' refers to kind. It also implies an either/or relationship. However, it does not explicitly state mutual exclusivity or behavior when neither is provided, leaving some ambiguity.
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 action ('Retry') and the resource ('failed queue job'), with specific modes: by id or all of a kind. This distinguishes it from sibling tools like wafle_system_queue_failed (listing) and wafle_system_queue_stats (statistics). The verb+object combination leaves no ambiguity about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The use case is implied strongly: it is for retrying failed queue jobs. While it does not explicitly name alternatives or exclusions, the context is evident from the action itself. Given the early position in the description, an agent will know when to select this tool, though it lacks explicit 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?
Annotations already declare readOnlyHint and idempotentHint, so the description is not required to restate safety. It adds value by disclosing the data content (last activity, items, optional email captured before exit), which goes beyond the structured annotations and gives the agent an idea of what the response will contain.
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: one defines the resource and contents, the other gives use cases. It is front-loaded with the primary action, contains no fluff, and every sentence contributes meaningful guidance.
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?
This is a read-only list tool with annotations covering safety, and schema covers all parameters. The description gives the purpose and the data fields included, which is sufficient for an agent to select the tool. However, it does not mention pagination or response shape, but those are not critical given no output schema and standard list behavior.
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% and each parameter already has a description (e.g., `with_email` states 'If true, only sessions where the user typed an email'). The description's mention of 'optional email captured before exit' adds a slight behavioral context, but mostly it aligns with the schema, 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 states a specific verb and resource: 'List abandoned cart sessions.' It further specifies what this includes ('last activity, items, optional email'), and the phrasing clearly distinguishes this listing tool from the sibling `wafle_abandoned_send_recovery` by implying a listing/analysis purpose rather than an action tool.
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 second sentence explicitly gives use cases: 'Use to estimate recovery potential or to feed a manual outreach campaign.' This provides clear context for when to use the tool, though it does not explicitly state when not to use it or name an alternative (e.g., `wafle_abandoned_send_recovery`).
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?
The description adds significant behavioral context beyond annotations: it specifies idempotency mechanics ('re-sending within the cooldown window is a no-op'), the return behavior ('wafle returns the existing send id'), and that the email uses the captured address. This proactively addresses common concerns (duplicate sends) and clarifies side effects, exceeding the idempotentHint and destructiveHint annotations.
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 short sentences, front-loaded with the core action, and every phrase earns its place. It avoids redundancy and is compact while covering purpose, behavior, and idempotency.
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 tool's side effect (sending email), no output schema, and 4 parameters, the description covers the main trigger, the cart pre-fill, the idempotency caveat, and the existing-send-id return path. It does not explicitly describe a successful send's return value, but the no-op case implies it returns a send id. For a non-destructive, idempotent tool, this is reasonably complete, though a one-line note on the normal response would make it fully self-sufficient.
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 75%, so the schema already documents slug, template, and coupon_code. The description helps clarify session_id as the abandoned-cart session identifier (implied by 'abandoned-cart session') but adds little else. The 'captured address' detail clarifies the email target, but template/coupon semantics remain fully in the schema. Overall, the description offers marginal additional parameter meaning.
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 a specific verb ('Trigger') and resource ('recovery email to the captured address of an abandoned-cart session'), and describes the email's content (one-click recovery link with cart pre-filled). This distinguishes it from siblings like wafle_abandoned_list and wafle_checkout_cart_recover.
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 its use case (abandoned-cart recovery) but provides no explicit when-to-use vs alternatives, no exclusions, and does not reference any sibling tools. The context is clear but there is no guidance on when this tool is preferred over similar recovery/checkout tools.
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?
Annotations already provide readOnlyHint and idempotentHint. The description adds valuable context about the cron detector (every 30 minutes), the fields included, and the notification behavior with cooldown, which goes beyond the annotations.
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 short paragraphs, front-loaded with the main purpose. The second paragraph adds useful context without fluff. Every sentence contributes meaning.
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 list tool with no output schema, the description provides a good overview of what anomalies include and the underlying detection cadence. It lacks a detailed return format, but the field enumeration partially covers it. Overall, reasonably 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 43%, and the description compensates by listing the possible values for 'kind' (cpa_spike, roas_break, etc.) and mentioning severity and scope. However, it doesn't explain parameters like 'since', 'acknowledged', or pagination, leaving some ambiguity.
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 'List ads anomalies detected by the cron-driven detector', using a specific verb and resource. It distinguishes this tool from siblings by focusing on anomalies, a unique concept among the listed tools.
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?
Explicitly says 'Use this tool to read raw history', giving a clear use case. It doesn't name alternatives, but the context of anomaly detection history is enough to differentiate from other wafle_ads tools.
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?
The description goes beyond the idempotentHint/destructiveHint annotations by specifying the actual state change (status to ACTIVE), confirming idempotency for already-active campaigns, and warning about the Learning Phase signal loss for long-paused campaigns. This provides valuable behavioral context.
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 plus a caveat note, all directly informative. The main action is front-loaded, and the note about Learning Phase is a valuable addition without padding.
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 two-parameter state-change tool with idempotency and destructive hints already provided, the description covers the essential behavior and adds a domain-specific caveat. It doesn't describe return values, but no output schema exists and the operation is straightforward.
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 provides full descriptions for both required parameters (slug and campaign_id) with examples, achieving 100% coverage. The description doesn't add parameter-specific semantics beyond referring to 'by id', so 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 explicitly states the action ('Resume a paused Meta Ads campaign by id') and the outcome ('Sets status to ACTIVE'), clearly distinguishing it from sibling tools like wafle_ads_campaign_pause or wafle_ads_bulk_pause.
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 clearly describes the scenario when this tool is appropriate (resuming a paused campaign) and notes a behavioral consideration for campaigns paused 14+ days, though it doesn't explicitly contrast with alternatives. The context is clear enough for an agent to select it.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds meaningful behavioral context beyond annotations: the response includes 'fatigue_score' (0..1, higher = more fatigued) and 'phase' ∈ {learning, active, fatigued, off}. It also clarifies that the output is a row-per-day timeseries, which is not evident from the schema or annotations alone. It does not mention pagination or ordering, but that is minor given the read-only, idempotent annotations.
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 short paragraphs, front-loaded with the core definition and then the use cases. Every sentence earns its place: the first sentence defines output structure, the second lists metrics, the third gives detection scenarios, and the fourth mentions additional response fields. No fluff 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 there is no output schema, the description compensates well by listing all metrics (spend, impressions, clicks, conversions, revenue, roas, frequency, ctr, cpm) and the computed fields (fatigue_score, phase with its enum values). It also covers interpretation guidance. However, it does not specify row ordering, handling of days with no data, or any pagination/limit behavior, which leaves minor completeness gaps for a tool with 4 parameters and no 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 schema already fully documents all four parameters (slug, creative_id, since, until). The description does not add significant new semantics beyond what the schema provides—it merely repeats 'since' and the inclusive lower-bound concept. Baseline 3 is appropriate because the schema carries the parameter documentation burden.
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: 'Daily timeseries for a single creative_id since `since`.' This clearly defines the tool's scope (single creative, daily granularity) and distinguishes it from siblings like wafle_ads_breakdown_by_creative or wafle_ads_performance_summary, which likely operate on broader dimensions. The metric list (spend, impressions, clicks, conversions, revenue, roas, etc.) further specifies what the tool returns.
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 use cases: 'Use to detect (a) Learning Phase exit, (b) creative fatigue (frequency rising + CTR falling), (c) the right scale moment (3+ days of stable ROAS above target).' This tells an agent exactly when to invoke this tool. However, it does not mention when not to use it or suggest alternatives (e.g., wafle_ads_breakdown_by_creative for comparing creatives), so it stops short of a full 5.
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?
Annotations already declare readOnlyHint and idempotentHint, so the description adds valuable context beyond that: the data sources, the return fields (meta_reported_orders vs wafle_orders), and the inclusion of a prev_period block. This gives the agent a good sense of what to expect without overstating operational details.
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 compact and front-loaded. The first sentence states the purpose, the second details output metrics and usage, with no wasted words. Every sentence carries meaningful information.
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 tool's complexity (joining two data sources, many return fields, no output schema), the description reasonably compensates by listing key metrics and the prev_period block. It could mention how days applies to both sources or define derived metrics more explicitly, but it is largely sufficient for a read-only summary 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 description coverage is 100%, so both parameters (days, slug) are fully described in the schema. The description does not add any additional parameter semantics but also does not need to; 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: account-level cross-tabbed performance, joining Meta marketing data with wafle CAPI orders/revenue. It also lists the specific metrics returned, distinguishing it from sibling tools like anomalies_list or compare_periods.
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 'Use this as the input to any optimization decision', providing clear context for when to use the tool. It does not, however, name alternatives or explicitly state when not to use it, hence a 4 rather than 5.
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 the effect (status change to active, eligibility for triggers) and importantly notes that it is a no-op if already active, indicating idempotency. This is transparent for a simple state-transition tool, though it does not discuss any prerequisites or side effects beyond the trigger eligibility.
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 short sentences: the first states the action and effect, the second adds important idempotency info. Every word earns its place, and the essential information is front-loaded.
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 2-parameter activation tool with no output schema, the description covers what the tool does, why it matters, and the no-op behavior. It is complete enough for an agent to use it correctly in context, though it could mention what response to expect.
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% (both `slug` and `agent_slug` have descriptive details), so the schema already documents parameter meaning. The description itself does not add further parameter semantics beyond the tool's purpose, 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 action ('Activate an agent'), the specific state change (moves status to `active`), and the consequence (eligible for scheduled/event triggers). This distinguishes it from sibling tools like wafle_agents_pause and wafle_agents_create.
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 context: this tool is used to enable an agent for scheduled/event triggers. It does not explicitly name alternatives or state when not to use it, but the purpose is unambiguous and implies its role in the agent lifecycle.
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 to fall back on, the description carries the burden of disclosing effects. It explicitly states that triggers stop firing and existing runs remain unaffected, which are key behavioral traits. It also implies the agent must be active, hinting at constraints. It lacks details on idempotency or error handling, but covers the core 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?
Two concise sentences, front-loaded with the primary action ('Pause an active agent'), followed by a precise behavioral note. Every word adds value, with no repetition of schema details.
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 2-parameter action with no output schema, the description adequately covers what the tool does and its side effects. It could mention return value or repeated-pause behavior, but these are not critical given the tool's simplicity and the rich 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%, with both 'slug' and 'agent_slug' fully described including examples and format rules. The description adds no parameter-specific details, which is acceptable since the schema already provides thorough semantics.
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+resource ('Pause an active agent') and adds behavioral scope ('Triggers stop firing; existing runs unaffected'). This clearly distinguishes it from sibling tools like wafle_agents_activate or wafle_agents_run, making the tool's 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?
It provides clear context for when to use the tool: pausing an active agent, with the added nuance that existing runs are unaffected. This implies the tool is not for stopping in-progress executions, guiding appropriate selection versus alternatives. However, it does not explicitly mention when not to use it or name alternatives.
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 full burden. It discloses that the tool returns a `run_id` and a synchronous run row with possible statuses (done, failed, awaiting_approval), which informs the agent about execution outcomes. It also hints at the need to poll via `wafle_agents_runs_get`, indicating the run is not necessarily final. However, it doesn't cover permissions, side effects, or error conditions.
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 action. No redundant information. The pointer to the polling tool is valuable.
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 there's no output schema, the description provides essential return information (run_id, statuses). It also instructs on the next step (polling). It doesn't detail the context parameter or possible errors, but for a dispatch action the core information is present. Sibling tools provide surrounding context.
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 all parameters are documented in the schema. The description doesn't add meaning beyond the schema, e.g., it doesn't elaborate on how `slug` or `agent_slug` relate. It is minimally sufficient due to the high schema 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 'dispatch' and identifies the resource as 'a run for an agent'. It clearly differentiates from sibling tools like wafle_agents_runs_get (poll) and wafle_agents_runs_approve/reject. It also states what is returned.
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 states this is for 'manually' dispatching a run, implying it's the tool to initiate a run rather than inspect or approve. It explicitly directs users to `wafle_agents_runs_get` for polling, which serves as an alternative for monitoring. It doesn't enumerate when not to use it, but the guidance is clear enough.
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?
The description explains key behavioral effects: it resumes execution from the pending tool call and saves an optional note to the audit log. This goes beyond the destructiveHint annotation by clarifying the mechanism and side effects, though it could further note irreversibility or permission requirements.
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 followed by a concise effect statement. There is no redundant or filler 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 straightforward approval action, the description covers the key aspects: target state, what happens next, and the audit note feature. It does not explain the return value or behavior when the run is not awaiting approval, but these are less critical given the simplicity and existing annotations.
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?
Only one of three parameters (slug) has a schema description, so overall schema coverage is low. The description adds meaning to the 'note' parameter (saved to audit log) and clarifies the run's state, but 'run_id' remains minimally elaborated beyond its obvious role.
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 action: approve a run that is awaiting approval and resumes execution. It distinguishes itself from the sibling tool wafle_agents_runs_reject by focusing on approval and resumption, not rejection.
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 clearly indicates when to use the tool: for runs in the 'awaiting_approval' state. It does not explicitly mention when not to use it or point to alternatives, but the context of approval vs. rejection is evident from the sibling tool names.
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?
The readOnlyHint annotation already indicates a safe read operation, and the description adds value by disclosing the response row fields (status, tokens, cost_cents, duration_ms) and confirming pagination/status filtering behavior. No contradiction exists.
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 core action, and wastes no words. It efficiently conveys purpose, key filtering, and output fields.
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 description gives a good overview of the response row contents and pagination/filtering, but does not specify the list response shape (e.g., array or object with pagination metadata). Given the tool's simplicity and the presence of a readOnlyHint, this is adequate though not 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 only 40% (slug and agent_slug have descriptions). The description adds context for status and pagination but does not explicitly explain page and per_page parameters beyond the word 'paginated'. It partially compensates for the coverage gap but leaves room for more detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'runs for an agent', distinguishing it from sibling tools like wafle_agents_runs_get (single run) and wafle_agents_runs_approve/reject (actions). It also specifies pagination and status filtering, making the tool's role 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 (listing runs for an agent) and implies its role alongside other run-related tools, but it does not explicitly mention alternatives or exclusions. Since there is no competing 'list' tool, the usage context is sufficient.
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. It discloses the job-based workflow ('Accept the job to write category overrides') and the return format (`{ category, confidence }` or null), which is valuable beyond what the schema provides.
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 covering purpose, input, output, and workflow with no redundant words. It is compact and front-loaded.
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 3-param tool with no output schema, the description covers input, output, and the job acceptance step. It omits details on how to accept the job, but sibling tool names (e.g., wafle_ai_jobs_accept) make that inferable.
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%, so parameters are fully documented. The description adds the output format but does not deepen semantics for slug, product_skus, or available_categories beyond the schema.
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: 'Auto-classify products without a category'. This uses a specific verb and resource, and distinguishes it from sibling AI tools like wafle_ai_translate or wafle_ai_product_describe by focusing on category assignment.
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 direct call instructions ('Call with a list of SKUs and a list of allowed categories') and scopes the use case to products without a category. However, it does not explicitly contrast with alternative tools or state when not to use it.
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?
Annotations already declare readOnlyHint and idempotentHint, covering the safety profile. The description adds that the tool is paginated and filterable, but does not go beyond that with details like response format, ordering, or error behavior. This is adequate but not rich, matching the baseline for annotation-covered tools.
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 of useful information with no filler. It front-loads the core purpose, then covers filters and usage examples. Every word adds value.
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 read-only, paginated list tool with no output schema, the description is solid. It states the resource, filters, and typical use cases. It does not describe the return fields or sorting, which a dedicated output schema would normally cover, but in its absence the description could be slightly more detailed. However, the tool name and filter list give enough context 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (page, slug, per_page have descriptions; status, job_type, user_review only have enums). The description explicitly names all three filter parameters and provides a concrete use case ('pending review' queue, which maps to user_review=pending), adding meaning beyond the bare enums. It does not explain each enum value, but the enums are self-explanatory.
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 'Paginated list of AI jobs for a store' with a specific verb (list), resource (AI jobs), and scope (store). It distinguishes from sibling tools like wafle_ai_jobs_get (singular fetch) and wafle_ai_jobs_accept/reject/edit (mutations), and the filtering by job_type, status, or user_review further differentiates it.
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: 'Use to surface a pending review queue or to find a specific recent job.' It implies use cases but does not explicitly mention alternatives (e.g., use wafle_ai_jobs_get for a single job), so it falls short of a full 5 but is still strong.
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?
The annotation idempotentHint=true is complemented by specific caching details: 'Cached by sha256(source_text|source_lang|target_lang) — re-translating the same input is free.' The description also discloses preservation of markdown, lists, links, and {{placeholders}}, going beyond the generic idempotency hint. No return format is given, but this is not a major gap for a simple translation 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?
Three dense, front-loaded sentences: purpose+caching, capabilities+use cases, and language code format. Every sentence adds value, and there is no redundant restating of schema or annotations.
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 4-required-param tool with no output schema and only idempotentHint, the description covers use cases, caching behavior, formatting preservation, and language code formats. It lacks explicit response format or error handling, but the overall context is sufficient for an agent to invoke the tool 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 100%, with each parameter (slug, text, source_lang, target_lang) already described in the schema. The description adds language code examples and context about text preservation, but these are broad behavioral notes rather than deeper parameter-level semantics. 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 opens with a specific verb and resource: 'Translate a piece of text from one language to another.' This clearly distinguishes the tool from sibling AI tools like wafle_ai_categorize or wafle_ai_product_describe. It also narrows scope to text snippets, 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 explicitly states when to use the tool: 'Use for product descriptions, emails, or short copy snippets.' This provides clear context. It does not name alternatives explicitly, but the 'short copy snippets' phrase implies a boundary against longer documents, though no excluded alternatives are named.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, and the description aligns with these. It adds behavioral context beyond the annotations by defining what qualifies as an abandoned cart and clarifying that results are filtered by a customer email hash. This enriches the agent's understanding without contradicting the safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the first packs the core purpose and definition; the second explains the contextual use case. No wasted words, front-loaded with the verb and resource. Excellent conciseness and 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?
For a simple list tool with 3 parameters, 100% schema coverage, and clear read-only/idempotent annotations, the description covers the core semantics (abandoned definition, email hash filter) and intended usage. It does not describe return values or pagination, but in the absence of an output schema, the term 'List' implies an array. The description is sufficiently complete for correct invocation.
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% for all three parameters, so the schema already documents 'slug', 'since', and 'customer_email_hash' with descriptions. The tool description mentions 'customer email hash' but does not add meaning beyond the schema. Baseline of 3 is appropriate; the description does not compensate or add parameter-level value.
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 verb 'List' with the resource 'abandoned carts', and provides a precise definition: 'cart_token has items but no paid order in wafle_orders'. It also scopes to 'for a customer email hash', distinguishing it from broader abandoned-cart listers like wafle_abandoned_list. The purpose is unmistakable.
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 'Used by retargeting drip flows to surface ... nudges', which provides clear usage context. It does not explicitly name alternatives or exclusions, but the intended use case is concrete. This meets the 'clear context, no exclusions' bar.
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?
Annotations already provide idempotentHint=true and destructiveHint=false, so the bar for additional disclosure is lower. The description adds meaningful behavioral context: the 422 error for webhook-driven gateways and the semantic conditions (proof-of-deposit verified, cash collected at delivery). This helps the agent anticipate failure modes, which is valuable beyond the annotations.
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, well-structured sentence that front-loads the core action and follows with a clear exclusion. Every phrase adds value, including the parenthetical validation conditions and the alternative handling note. No redundant or extraneous information.
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 relatively simple state-transition tool, the description covers the who (manual operation), what (mark as paid), when (transfer/cash verified), and the key edge case (422 on webhook gateways). It lacks explicit success response details, but with no output schema and the tool's low complexity, the description is sufficiently complete for an agent to use 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 covers 67% of parameters with descriptions (slug and proof_ref), but order_id lacks a description in the schema. The tool description does not add further clarification for order_id or explain how the parameters relate. Since the description doesn't compensate for the uncovered parameter and the coverage is moderate, a 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 action: manually flipping a transfer/cash order to paid. It distinguishes from sibling tools like refund or cancel by specifying the exact condition (transfer/cash) and the exclusions (webhook-driven gateways). The verb 'flip' plus the resource 'order' and state 'paid' make 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 explicitly says when this tool applies (transfer/cash orders with verified proof) and when it does not (webhook-driven gateways like mp/stripe, which are handled automatically via /webhooks/*). It provides a clear alternative path for excluded cases, though it does not name a specific sibling tool. This is stronger than implied usage.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by describing the checkout pipeline state flow (cart→MP/Stripe/transfer→paid) and the filtering capabilities. This goes beyond the structured metadata without contradicting it.
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 primary purpose front-loaded. It efficiently conveys the resource, the pipeline, the key filters, and the alternative legacy tool without any fluff 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?
For a read-only list tool with annotations and a schema that already covers defaults and parameter descriptions for several fields, the description provides adequate context: the pipeline, key filters, and a critical alternative. It does not explain response shape or pagination behavior, but these are less critical given the readOnly and idempotent hints and the schema's limits.
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 only 43%, so the description should compensate. It explicitly mentions status, since, and email as filters, and the slug/store context, but does not provide semantics for limit, offset, or until. The description adds some meaning to the status filter and the since format, but the gaps in parameter documentation remain.
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 'List orders from the wafle_orders table for a store,' naming the specific verb and resource. It also distinguishes itself from the sibling `wafle_orders_list` by explicitly noting the different table and legacy WC orders.
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 provides explicit guidance to use `wafle_orders_list` for legacy WC orders, creating a clear exclusion. It also mentions the filterable dimensions (status, since, email) and the new checkout pipeline, implying when this tool is appropriate. It lacks explicit 'use this when' phrasing, but the alternative direction 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?
Annotations already state idempotentHint=false and destructiveHint=false. The description adds valuable context: the tool is long-running, emits progress notifications with rows processed/total, and returns a summary with imported/updated/errors/duration. This goes beyond the annotations without contradicting them.
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 short sentences plus a compact return summary list. It is front-loaded with the core action and avoids redundant or vague filler.
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 long-running tool with no output schema, the description covers the execution model, progress events, and return value. It does not explain the mapping parameter, but the schema does. The description is sufficiently complete for an agent to understand what to expect and how the tool behaves.
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 high (75%), with descriptions for slug, csv_url, and mapping. Timeout_seconds lacks a description but has default/min/max. The tool description does not add further semantics 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 the tool imports a CSV product feed into a store with catalog_mode=csv. This specific verb+resource combination distinguishes it from siblings like wafle_products_sync_trigger and wafle_products_create_manual.
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 provides clear context by specifying the target store mode (catalog_mode=csv) and the long-running nature, implying when it applies. However, it does not explicitly mention alternative tools or situations where it should not be used.
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?
Annotations already cover read-only and idempotent behavior. The description adds useful architectural context that customers are derived from orders. However, it mentions 'has-orders' as a filter, which is not present in the input schema, potentially misleading 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?
Two succinct sentences; the first conveys the primary function and filters, the second provides essential architectural context. 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?
The description covers core functionality, filters, pagination, and an important data-model insight. It does not describe return format or sort order, but for a straightforward list tool with good schema coverage, this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80%, but the description adds meaning for the 'search' parameter ('by email/name') and clarifies the derived-data concept. The 'has-orders' mention is problematic since it is not a schema parameter, and page/per_page details are left to the schema.
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 explicitly states 'List customers of a store with pagination + filters' and lists specific filter types ('search by email/name, has-orders, segment'), distinguishing it from siblings like wafle_customers_get and wafle_customers_orders.
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 context is clear: it is a listing tool with pagination and filters. However, it does not explicitly mention alternatives or when not to use it (e.g., for single customer lookup), so it falls short of a 5.
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?
Discloses provider-specific API calls and states it is read-only on the upstream provider, adding value beyond the annotations. Does not detail local side effects, but annotations already cover idempotency and read-only hints, so the added context is sufficient.
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 main action, followed by provider details and usage timing. Every sentence earns its place with 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?
For a simple one-parameter tool with no output schema, the description provides good context on what it does, when to use it, and provider-specific behavior. It does not mention return values or failure modes, but the scope is appropriately covered.
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 has one required parameter (gateway_id) with no description (0% coverage). The description indirectly implies gateway_id by referring to wafle_gateways_create/update, but does not explicitly define it. This partially compensates 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?
Description clearly states the tool runs a live credential test against the gateway provider, with provider-specific behavior (MP, Stripe, transfer). This distinguishes it from siblings like wafle_gateways_create or wafle_gateways_list.
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?
Explicitly says to use after wafle_gateways_create or wafle_gateways_update for rotated creds, providing clear timing context. Does not explicitly mention when not to use or alternatives, but the sequencing guidance is strong enough for a 4.
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?
The annotation provides destructiveHint:false and openWorldHint:false, but the description adds valuable behavioral detail: it sends an invitation email with a magic link and requires specific permissions. This goes beyond the structured annotations and informs the agent 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 short, focused sentences. The first sentence states the purpose clearly, and the second provides the key prerequisite. No wasted words or redundant information.
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 relatively simple creation tool with no output schema, the description covers the action, the side effect (email with magic link), and the permission requirement. Minor gaps like which tenant identifier to provide are not fully clarified, but overall it is sufficient for correct invocation.
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 complete descriptions for all four parameters (100% coverage), including the role enum, email format, and the alternative tenant_id/tenant_slug. The description does not add more parameter-level detail beyond what the schema already includes, so a 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 the action (invite) and the object (teammate to a tenant by email), differentiating it from sibling tools like wafle_members_list and wafle_members_update_role. The verb and resource are 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the prerequisite that the actor must be an owner or admin of the target tenant, which guides when this tool can be used. It does not explicitly name alternatives, but the context is clear enough among the sibling tools.
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?
Annotations include idempotentHint=false and destructiveHint=false, but the description adds the key behavioral warning that manual creates on sync stores will be overwritten. This goes beyond the annotations and informs the agent of a side effect. The description doesn't fully detail all mutation behaviors, but it provides the most critical caveat.
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 core purpose and immediately followed by a critical exclusion. Every word earns its place, and the structure makes the tool's usage boundary clear without unnecessary verbosity.
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 description provides essential usage context and the critical sync-store risk, but it lacks information about return values, required permissions, or parameter details. With 9 parameters, no output schema, and no description of what happens on success, the description is only minimally complete for a create tool of this complexity.
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 only 22%, and the description provides no additional parameter explanations. Most parameter names (name, price, stock, etc.) are self-explanatory, but the description doesn't clarify nuanced fields like 'status' enum values or the relationship between 'sku' and required fields. Since the schema leaves most parameters undocumented, the description should have compensated but didn't.
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 and resource: 'Manually create a product in a store whose catalog_mode = manual.' It clearly distinguishes itself from wafle_products_override by noting the sync store context, so the tool's scope is unambiguous.
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 explicitly states when to use the tool (catalog_mode = manual) and when not to (catalog_mode = supabase_sync), and names the alternative tool (wafle_products_override). It also warns about data loss ('overwritten on next sync'), which is actionable 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?
Annotations declare readOnlyHint and idempotentHint, so the safety profile is known. The description adds behavioral context beyond annotations by explaining that it makes one API call per configured carrier and reports statuses with latency. No contradiction with annotations.
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 action and resource. Every word adds value: what it does, what it reports, and when to use it. 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 simple diagnostic tool with no output schema, the description covers purpose, behavior, output summary, and usage trigger. It is slightly light on response structure details, but adequate for an agent to select and invoke 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 100% for the single param (slug), with a clear example. The tool description does not add extra meaning beyond the schema, which is acceptable given high coverage. Baseline 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?
Description uses a specific verb+resource ('Run the carrier connection self-test') and clearly states what the tool does: 'Hits each configured carrier API once and reports ok|degraded|down + latency.' This distinguishes it from sibling tools like wafle_gateways_test or wafle_system_health.
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?
Provides explicit when-to-use guidance: 'Use when shipping rates are flaky or empty.' While it doesn't mention alternatives or when-not-to-use, the context is clear and actionable, meeting the 'clear context, no exclusions' criterion.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds value by specifying that the tool 'Returns one row per available carrier' with a list of carriers and the cost+ETA fields. This discloses output behavior beyond the annotations without contradicting them.
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 with front-loaded primary purpose and a second sentence for usage guidance. No redundant information; every sentence contributes value.
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 read-only idempotent tool with no output schema, the description covers core behavior, carrier list, and return fields. It omits edge cases like no carriers available or optional subtotal, but the annotations and simple return shape make the description adequate.
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 50% (slug and subtotal have descriptions). The description mentions 'destination + cart' and the debugging use case, but does not detail item structure, destination field requirements, or the optionality of subtotal. It adds marginal meaning beyond what the schema already provides, and the schema's nested objects remain self-explanatory by name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States 'Quote shipping rates for a destination + cart' with a specific verb and resource, enumerates the considered carriers (andreani, oca, viacargo, retiro, gratis), and specifies the return shape (cost + ETA). This clearly distinct from sibling tools like wafle_shipping_carriers_status by focusing on rate quotes rather than carrier status.
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?
Provides explicit use cases: 'estimate before checkout' and 'debug why isn't carrier X showing up?'. This gives clear context for when to invoke. It does not name specific alternatives or exclusions, but the guidance is actionable and 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?
Annotation gives idempotentHint, and description adds PATCH semantics ('Only the fields you pass are changed') which is valuable beyond the annotation. It also lists common editable fields. No contradiction with annotations.
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 concise, front-loaded sentences. First sentence states action and PATCH semantics; second gives common field examples and an alternative tool. Every word 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?
Given the moderate complexity (11 optional params, no output schema), the description covers the essential semantics, common use cases, and an alternative. It lacks mention of return value or settings-related sibling tools, but is otherwise adequate.
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 only 36%, so description partially compensates by naming common edits (theme_color, domain, free_shipping_from, payment_methods, shipping_methods). However, many parameters (e.g., cbu_cuit, cbu_alias) receive no explanation in either schema or description.
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?
Description states 'Update top-level store fields' with a specific verb and resource, and clarifies PATCH semantics. It distinguishes from siblings by noting 'top-level' fields and explicitly directing pixel/marketing ID changes to wafle_pixels_set.
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?
Provides clear context with common edit examples and explicitly names wafle_pixels_set as an alternative for pixel IDs. However, it does not explicitly exclude wafle_stores_settings_update or state when not to use the tool.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not need to restate those. It adds behavioral context by explaining the filtering dimensions (store, actor type, endpoint, date range) and the forensic use case. There is no contradiction with annotations.
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 short sentences. The first states the core purpose and filters; the second gives concrete use examples. Every sentence earns its place, and the most important information is front-loaded.
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 read-only query tool with no output schema, the description covers the essential context: what the tool does, the key filters, and example queries. Pagination behavior is implied through page/per_page schema defaults but not explicitly described, and the return format is not specified, though that may be acceptable for a simple list query.
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 only 43%, so the description must compensate. It does clarify the purpose of store_id, actor_type, endpoint, and date range (from_ts/to_ts). However, actor_type is described as '(master/store)' while the enum includes 'system' as well, which is an incomplete and slightly misleading characterization. Page/per_page already have schema descriptions, so they don't need extra 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 queries the audit log ('who called what, when'), specifies the resource (audit log), and distinguishes it from sibling tools by its unique focus on audit forensics. The verb 'Query' is specific and accurate.
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 use cases for forensics ('who refunded order 87?', 'who toggled gateway 65 inactive?'), which gives clear guidance on when to use the tool. However, it does not mention alternatives or situations where the tool should not be used, so it stops short of full exclusionary 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?
Annotations already indicate idempotent and destructive hints. The description adds valuable behavioral details: partial success visibility (per-id success/failure) and a 1 RPS throttle to respect Meta's rate limit. No contradiction with annotations.
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?
Three sentences, each earning its place: purpose, return behavior, and usage context. Front-loaded with the action, no 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?
Despite lacking an output schema, the description explains the return format (per-id success/failure). It covers purpose, use cases, behavior, and throttling, making the tool fully understandable for its complexity.
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%, and both parameters (slug, campaign_ids) are well-described in the schema. The description reinforces the bulk nature but adds no new parameter-specific semantics beyond the schema.
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 verb and resource: 'Pause many Meta campaigns in a single tool call.' It distinguishes itself from siblings like wafle_ads_campaign_pause by emphasizing the bulk nature and per-id success/failure reporting.
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?
Explicitly provides use cases: 'Best for ROAS-floor sweeps... and seasonal cleanup.' It also notes the backend throttling behavior, helping agents decide when this tool is appropriate. However, it does not explicitly contrast with the single-campaign pause sibling.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds value by disclosing that the response will contain system_prompt, tools_allowed, guardrails, trigger_config, and stats counters, giving the agent concrete expectations of the return payload. No contradictions with annotations.
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 sentence that starts with the action and resource, then lists key payload elements. Every word serves a purpose, with no redundancy or vague language.
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 two-parameter read operation, the description fully covers what the tool returns (full definition with key fields). Combined with complete schema and annotations, no critical information is missing. The absence of an output schema is mitigated by the explicit field list.
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 both 'slug' and 'agent_slug' fully documented. The description adds only that the lookup is 'by its slug', which aligns with the schema but doesn't go beyond it. Per the baseline, a score of 3 is appropriate when schema does the heavy lifting.
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 'Get' with the resource 'one agent by its slug', clearly distinguishing it from sibling tools like wafle_agents_list (plural) or wafle_agents_run (execution). It also lists the contained fields, making the tool's scope explicit.
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 the tool is for retrieving a single agent's detailed definition when you know its slug, which is a clear use context. It doesn't explicitly mention alternatives or exclusions, but the purpose is evident for a singular get operation alongside list/create/update siblings.
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?
Annotations already declare readOnlyHint and idempotentHint; description is consistent and adds return-content context: agents have system_prompt, tools whitelist, guardrails, and trigger. No contradictions or destructive behavior implied.
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 concise sentences, front-loaded with the core action and entity, plus compact filter enumeration. Every word contributes.
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?
Despite lacking an output schema, the description states what each listed agent contains and the available filters. This is sufficient for a straightforward list operation with idempotent/read-only annotations.
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 only describes slug (33% coverage), while description confirms status and trigger_type as optional filters and enumerates status values. This adds some meaning but doesn't fully explain trigger_type values or filter behavior beyond the schema enums.
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 'List custom agents defined for a store', a specific verb+object that clearly names the resource. It distinguishes from sibling get/stats/runs tools by targeting custom agent definitions rather than runs or templates, and notes filtering capabilities.
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 provides clear context by stating the store slug and optional status/trigger_type filters. It does not explicitly name alternative tools or exclusion cases, but the list scope and filter options make intended usage 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?
Annotations already declare readOnlyHint and idempotentHint, so the description need not restate safety. It adds useful behavioral context by enumerating the response contents (statuses, SSL expiry, verification token, DNS instructions) and the three verification methods, going beyond the annotations without contradicting them.
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 main action, and every clause adds value. No redundant phrasing 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 read-only list tool with a clear schema and annotations, the description covers purpose, return values, and when to use it. No output schema exists, but the description explicitly lists the return fields, making the tool behavior complete for an agent.
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 67% (slug and status are described; limit is not). The description implies the slug identifies the store ('store X') but adds no explicit detail about limit or status beyond what the schema provides. It does not fully compensate for the missing limit semantics, but the remaining parameters are self-explanatory.
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 'List the custom domains attached to a wafle store,' which precisely identifies the verb (list), resource (custom domains), and scope (per store). It further details the returned fields (status, SSL expiry, verification token, DNS-setup instructions), clearly distinguishing it from domain add/status/verify siblings.
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 'Use first when the user asks "what domains does store X have?" or before giving DNS instructions to a new tenant,' giving clear use cases. It does not name alternatives or say when not to use, but the context is strong enough for an agent to know when to invoke it.
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?
Beyond the destructiveHint annotation, the description adds crucial behavioral details: 'Destructive and irreversible' and 'Confirm with the user'. It also discloses the failure condition for default gateways, which is not captured in annotations. These details meaningfully exceed the structured data.
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 compact and front-loaded. Three short sentences state the action, a key failure condition, and a safety warning, with no extraneous information. Every sentence 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 1-parameter delete operation, the description covers the essential caveat (default store) and warns about irreversibility. It does not mention return values or behavior for non-existent gateways, but these are less critical given the simplicity and the clear warnings.
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 parameter, gateway_id, with type and minimum but no description. The tool description does not explain this parameter beyond the name itself. Since schema description coverage is 0%, the description should compensate but does not explicitly clarify that gateway_id is the unique identifier of the gateway to delete.
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 'Delete a gateway', a specific verb and resource. This clearly distinguishes it from sibling tools like wafle_gateways_create, wafle_gateways_update, wafle_gateways_list, and wafle_gateways_test.
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 key usage context: it fails if the gateway is the default for a store, and tells the user to switch the store first. This is clear when-to-use and a necessary precaution, though it does not explicitly mention alternatives like updating instead of deleting.
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?
Despite annotations already indicating destructive and idempotent behavior, the description goes beyond them by specifying that the order moves to 'cancelled', inventory is restocked, and the refund condition (gateway support and payment status). It also includes the crucial instruction to confirm with the user, providing rich behavioral context.
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, with two sentences that each add essential information: the core action and the destructive consequences plus user confirmation. There is no waste or redundancy, and the structure is easy to parse.
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 destructive operation without an output schema, the description covers the key behavioral aspects, including cancellation, refund, inventory restock, and user confirmation. It does not explain return values or error cases, but given the side effects are clearly disclosed, it is reasonably 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?
The schema covers only 2 of 4 parameters with descriptions, and the tool description does little to clarify the missing ones (reason, order_id). It indirectly explains the 'refund' parameter via the auto-refund note, but fails to add meaning for the other parameters, leaving gaps that the schema does not fill.
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 begins with 'Cancel an order,' a specific verb and resource, clearly distinguishing it from other order-related tools like wafle_orders_refund or wafle_checkout_order_refund. The extra detail about auto-refund further clarifies its unique role.
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 the tool is for canceling orders, but it does not explicitly state when not to use it or mention alternatives. However, the context is unambiguous and the guidance to confirm with the user adds practical usage direction.
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?
Annotations already declare readOnlyHint and idempotentHint, and the description adds valuable context: it identifies the specific pixel platforms and that the operation fetches 'current' configurations. No contradictions with annotations. It lacks details about return format, but this is a simple read.
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 that is front-loaded with the verb and resource, includes the platform list, and contains no superfluous words.
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 fully covers what the agent needs to know: action, resource, and supported platforms. The complexity is low, so no additional context is required.
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 provides 100% coverage for the single 'slug' parameter with a clear description, pattern, and length constraints. The description mentions 'a store' but adds no additional parameter-level meaning beyond the schema, so it meets the baseline for high schema 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 ('Fetch') and specifies the exact resource ('current marketing pixel IDs configured for a store') and the platforms (Meta, TikTok, GA4, Google Ads), which clearly distinguishes it from the sibling tool wafle_pixels_set.
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 use for retrieving current pixel IDs, and the sibling list provides context (there is a wafle_pixels_set for updates). However, it does not explicitly state when not to use it or name alternatives, so it falls short of a 5.
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?
Annotations only provide idempotentHint=false. The description adds behavioral context such as fixed_price 'overrides multiplier' and the warning about production impact, but doesn't disclose other side effects like whether an existing rule is overwritten or what permissions are required.
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 well-structured with a bulleted list and a clear cautionary note, front-loading the core purpose. Each sentence adds information without 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 description covers the main rule types, value formats, and a preview step, but omits that `target` is effectively required for `category_markup` and `fixed_price`, and doesn't mention the output of creation. Still, it's fairly complete given the schema and annotation coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description thoroughly explains the `value` parameter for each type, with an example for multiplier, and clarifies the meaning of each `type` enum value. This compensates for the 50% schema coverage and adds significant meaning beyond the input schema.
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 'Create a new pricing rule', a specific verb+resource, and then enumerates four rule types with their effects, clearly distinguishing this create operation from update/delete/list siblings. It also provides concrete examples like '2.2 = +120% on every base price'.
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 instructs to 'Always preview with wafle_pricing_compute_preview before committing rules in production', providing a clear prerequisite and companion tool. However, it doesn't explicitly state when to use update/delete instead, relying on the tool name for that distinction.
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?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds value by specifying the return payload (variants, images, attributes, overrides), which is useful context beyond the annotations. No contradictions.
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 with no filler. The key action and resource are front-loaded, and every word contributes meaning.
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?
The tool is a simple read operation with strong annotations and fully documented parameters. The description explains the return content, making it complete without needing 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?
The schema has 100% coverage with descriptions for both parameters, so the baseline is 3. The description adds marginal clarification ('slug (the URL-friendly id)') but mostly paraphrases the schema. It does not introduce new syntax or format details beyond what the schema 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 ('Fetch') and resource ('single product by slug'), clearly distinguishing it from sibling tools like wafle_products_list or wafle_products_search. It also states what is returned ('full detail including variants, images, attributes and overrides'), which further clarifies scope.
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 usage for retrieving a single product by slug, which is distinct from list/search tools. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to select it appropriately.
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?
The description discloses PATCH semantics ('only the fields you pass change'), which goes beyond the idempotentHint annotation. It also adds a valuable behavioral caveat about sync stores and sync engine respection. It does not mention permissions or error conditions, but with annotations present this is a strong contribution.
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 short sentences, front-loaded with the core purpose and followed by a single high-value usage guideline. Every sentence earns its place; 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?
The description covers the most critical contextual aspects: what the tool does, PATCH semantics, and when to prefer an alternative. It does not describe return values, but there is no output schema and the operation is straightforward. The sync-store caveat and PATCH clarification make it reasonably complete for an update tool.
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 13% (only slug has a description). The description adds 'numeric id' for product_id and PATCH semantics, but it does not explain the other parameters such as price, stock, images, or status. With such low schema coverage, the description should compensate more, but it doesn't.
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+resource pattern: 'Partial update of a product by numeric id.' It immediately conveys PATCH semantics and clearly differentiates from the sibling tool wafle_products_override, which is mentioned as the preferred alternative for sync stores.
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?
Explicit guidance is given: 'For sync stores, prefer `wafle_products_override` so the sync engine respects your tweaks.' This tells the agent exactly when to use this tool versus a closely related one, including the context that triggers the preference.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, so safety profile is covered. The description adds the return structure (name, description, argument schema) but no deeper behavioral details like pagination or rate limits, which are likely unnecessary for this simple listing 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?
Two sentences, front-loaded with the action 'List', and every sentence adds value: what it lists, what it returns, and a useful client scenario. No fluff or redundancy.
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 list tool with no parameters, good annotations, and no output schema, the description is complete: it states the resource, return content, and a specific use case. Nothing critical is missing.
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, and the schema is empty with 100% coverage. With no params to document, the description cannot add parameter semantics, but the baseline of 4 applies since there is nothing lacking.
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 lists server-defined prompts and specifies what is returned (name, description, argument schema). This distinguishes it from all sibling tools, which focus on ads, orders, agents, etc., and is the only prompt-listing tool.
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 provides an explicit use case: 'Useful for clients that don't surface the prompts/list MCP method.' This implies the alternative (using the native MCP method) and when to prefer this tool, though it lacks a full when-not/alternatives explanation.
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?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is known. The description adds behavioral context by listing specific configuration fields returned and noting the tool is needed to obtain the current shape for delta updates. This goes beyond annotations by clarifying the tool's role in an editing workflow.
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 exactly two sentences: the first states the primary purpose and enumerates return contents, the second offers a concise usage guideline. Every sentence carries value; there is no redundancy or fluff. The structure is front-loaded with the core purpose.
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 single-parameter, read-only tool with no output schema, the description is complete. It explains what is returned (full configuration with specific components) and why to use it (before editing settings to get the delta shape). This covers the essential context an agent needs, and the annotations cover safety.
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 fully describes the single 'slug' parameter with a pattern, length constraints, and example. Schema description coverage is 100%, so the description does not add meaningful parameter semantics beyond what the schema already provides. The baseline of 3 is appropriate when the schema carries the 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 the tool fetches the full configuration of a single store, with a specific verb ('Fetch') and resource ('configuration of a single store'). It enumerates internal contents (payment gateway IDs, shipping methods, CBU/alias, social pixels, theme, abandoned-cart settings), which distinguishes it from sibling tools like wafle_stores_list or wafle_stores_settings_get.
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 second sentence provides explicit guidance: 'Use before editing settings — you need the current shape to send a delta.' This tells the agent when to invoke the tool, though it doesn't mention when not to use it or explicitly name alternatives. Overall, the usage context is clear and actionable.
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?
Annotations already declare readOnlyHint and idempotentHint, so the description's additional detail that results include the 'last error' adds behavioral context beyond those annotations. No contradiction exists; the description aligns with the read-only and idempotent nature.
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: the first front-loads the core purpose, the second adds a useful pairing note. Every word adds value and there is no redundancy.
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 list tool with one parameter and no output schema, the description is complete. It states what jobs are listed and what error information is included, and the schema fills in the limit parameter. The pairing note gives practical context for a workflow.
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 single parameter 'limit' is self-explanatory in the schema with type, default, min, and max, so the description's omission is not a major gap. However, with 0% schema description coverage, a brief mention in the description could have added a bit more clarity, but the schema already suffices.
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 action ('List failed queue jobs') and the detail included ('with their last error'). The name 'wafle_system_queue_failed' is reinforced, and the sibling reference to retry helps distinguish this tool from related queue operations.
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 implicitly conveys when to use it by focusing on failed jobs and the last error, and the pairing note with wafle_system_queue_retry suggests a workflow. However, it does not explicitly contrast with other queue tools like wafle_system_queue_stats, so it lacks full exclusion 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?
The description goes beyond the idempotentHint annotation by disclosing that the tool returns the membership for the tenant and errors with `wafle_users_no_membership` if the user is not a member. This adds useful behavioral context not captured in structured fields.
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 compact and front-loaded, consisting of two sentences that directly state the purpose, effect, return value, and error condition. Every sentence earns its place without redundancy.
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?
With a single parameter and no output schema, the description covers all essential information: the session state change, the return value (membership), and the error scenario. It is complete for the tool's simplicity and rich sibling context.
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 complete description of `tenant_id` (numeric tenant id, CPT post id of the store) with 100% coverage. The tool description does not add additional parameter semantics beyond what the schema offers, 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's action: setting the session's `current_tenant_id` so subsequent calls apply to that tenant. It distinguishes this from sibling tools by explaining the effect on subsequent calls and mentioning the membership return value.
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 explains when to use this tool: when you want subsequent calls without an explicit `/stores/<slug>/` path to apply to a specific tenant. It implies the alternative of using explicit paths, but does not explicitly name alternative tools or list exclusions.
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?
Annotations include destructiveHint: true, and the description adds that direct calls without following the scaling rule could 'blow the Learning Phase'. It also clarifies that cents are in the ad account currency, adding context beyond the annotations.
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 short paragraphs, front-loaded with the primary action. Every sentence adds relevant operational detail with no filler.
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 four params and no output schema, the description covers purpose, parameter selection, constraints, and a risk warning. It doesn't describe the return payload, but the schema and annotations provide ample structured context.
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 all four parameters, but the description adds value by marking daily_budget_cents as preferred and emphasizing the mutual exclusivity constraint, plus the currency clarification.
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 'Update a Meta campaign's budget', clearly stating the verb and resource. It further specifies the two mutually exclusive budget parameters, distinguishing it from sibling tools like pause/resume.
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 identifies daily_budget_cents as preferred and explicitly notes the mutual exclusivity in the Marketing API. It also advises mirroring the recommender's +30% / max +50% rule when calling directly, providing practical guidance on how to use the tool safely.
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?
Annotations declare readOnlyHint=true and idempotentHint=true, so the read-only nature is already known. The description adds valuable context: 'Both ranges are evaluated against the wafle CAPI server-side truth' and explains why this ensures honest comparisons. This goes beyond the annotations by clarifying the data source and reliability motivation.
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 core purpose and metrics. It efficiently includes examples, data-source rationale, and constraints without redundancy. Every sentence 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?
The description covers the tool's purpose, usage scenarios, metrics, data-source semantics, and a key constraint. Since there is no output schema, it reasonably lists the metrics returned (spend, revenue, ROAS, CPA, conversions, profit) but could be slightly more specific about the output structure. Overall, it is sufficiently complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only slug has a direct top-level description). The tool description compensates by clarifying the relationship between period_a ('newer') and period_b ('baseline'), providing examples of acceptable formats, and adding the crucial non-overlap constraint. It also lists the metrics returned, which helps interpret the periods.
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: 'Compare two date ranges ... and return delta % per metric: spend, revenue, ROAS, CPA, conversions, profit.' It is specific about the operation (compare) and the resource (ad periods), and it differentiates itself from sibling tools by focusing on comparison rather than a single-period summary.
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?
Provides explicit use cases: 'Use to answer "how did April do vs March?" or "did the new creative pack improve things in the last 14 days vs the prior 14?"' It also explains why this tool is preferable (CAPI server-side truth vs Meta's pixel drift) and includes a constraint (windows must not overlap). It does not name alternative sibling tools but gives clear contextual guidance.
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?
Beyond annotations, the description discloses that the tool waits until the sync finishes, emits progress notifications, and is long-running (5+ minutes for large catalogs). This adds meaningful behavioral context not present in the annotations.
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 brief, front-loaded with the core action, and well-structured into two short paragraphs. Every sentence adds value: the action, the wait behavior, the progress notifications, the duration, and the alternative for fire-and-forget.
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 description covers the main behavior (wait, progress, long-running) but lacks details about the return value, error behavior, or how parameters like timeout_seconds interact with the process. The mention of 'underlying create endpoint' is vague, 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?
The description provides no parameter-level details. While the schema has a description for 'filters', 'connection_id' and 'timeout_seconds' are undocumented in both the schema and the description. With schema coverage at only 33%, the description should compensate but does not.
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 states a specific action: run a full ads-platform catalog sync and wait until it finishes. It distinguishes from fire-and-forget behavior by explicitly pointing to the underlying create endpoint, making the tool's purpose clear and differentiated.
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 says to use this tool when you need to wait for completion and receive progress notifications, and it names the alternative for fire-and-forget scenarios ('call the underlying create endpoint directly'). This is clear when-to-use and 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?
No annotations are provided, so the description must carry behavioral details. It discloses hard caps on max_cost_per_run_cents (5000 = USD 50) and max_turns (50), and lists the five pre-armed template names. It does not mention potential errors, idempotency, or whether the agent is immediately active, but the key constraints and operational options are disclosed.
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 compact and organized into two numbered paths, making the alternative workflows easy to scan. It passes along critical constraints in a single closing sentence without redundancy. Every sentence adds an operational fact.
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 tool's complexity (13 parameters, nested guardrails/trigger_config, no output schema), the description covers the two creation modes, prerequisite discovery, and numeric caps. It omits explanation for some optional parameters (model, temperature, tools_disallowed) but the schema contains enough property definitions for those. Overall, the description supplies the essential context beyond the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 23%, so the description compensates by enumerating the from-scratch parameters (name, system_prompt, tools_allowed, guardrails, trigger_type, trigger_config) and by listing the valid template values. It also maps the cap names to their limits, giving context beyond raw schema definitions. Some parameters like tools_disallowed and model are not explained in the description, but the main paths are covered.
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 'Create a new custom agent,' a specific verb and resource, and clearly distinguishes from sibling tools like wafle_agents_update or wafle_agents_run by detailing two creation paths. It also names the exact template options and outlines the from-scratch parameters, making its scope unmistakable.
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 tells the agent to use wafle_agents_tool_catalog first to discover available tools, giving a prerequisite for from-scratch creation. It also differentiates the two creation paths and notes that slug/name can be overridden when cloning. It does not explicitly name alternative tools like wafle_agents_update for editing, but the 'create' orientation is clear enough.
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?
Annotations only declare non-idempotence and non-destructiveness; the description adds valuable behavioral context: it generates a verification_token, returns 3 alternative DNS instructions, and lists validation constraints (lowercase FQDN, no IPs/wildcards, no .wafle.click subdomains, max 10 domains). It also discloses the asynchronous verification path via cron. No contradiction with annotations.
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 compact yet information-dense. The first sentence states the primary action, the second explains the follow-up workflow, and the third lists validation rules. Every sentence earns its place with no redundancy or filler.
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 creation tool with 7 parameters and no output schema, the description covers the core workflow, return value (DNS instructions), and validation rules. It also references the sibling wafle_domains_verify for the next step. It does not specify the exact response payload shape or behavior on duplicate domains, but that is not essential given the schema and sibling context.
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 already documents all 7 parameters with 100% coverage, so the baseline is 3. The description adds significant validation constraints not present in the schema (e.g., no wildcards, no IPs, no .wafle.click subdomains, max 10 active domains), which helps the agent craft valid requests. It does not deeply explain enum interactions, but the schema's param descriptions already cover those.
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 'Attach a new custom domain... to a wafle store', a specific verb+resource statement that clearly identifies the tool's function. It further differentiates from sibling wafle_domains_verify by explaining the creation-then-verification workflow. The example domain and mention of DNS instructions make the purpose concrete 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs the tenant to update DNS and then call `wafle_domains_verify` or wait for the 5-min cron, providing clear post-creation steps and an alternative. It does not explicitly contrast with wafle_domains_list or wafle_domains_status, but the creation vs. verification distinction is clear enough for selection.
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?
Beyond the idempotentHint annotation, the description reveals the full multi-step pipeline including probing TXT/CNAME/file methods, Let's Encrypt via acme.sh, nginx config rendering and reload, marking the domain active, and appending log events. It also discloses the 1-attempt-per-minute rate limit and the prerequisite that the domain must be previously added. This is substantial behavioral context not visible in structured annotations.
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 compact and front-loaded with the main action, followed by a clearly numbered pipeline and a final caveat. Every sentence adds new information with 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 description thoroughly details the side-effectful process, rate limits, and idempotency, and it sets the prerequisite of a previously-added domain. However, with no output schema present, it does not describe the response shape or failure behavior, leaving a slight gap for a tool that triggers a multi-step process.
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 100% coverage with clear descriptions for both `id` and `slug`. The description does not add any additional parameter-level semantics, but this is not necessary given the thorough schema coverage; 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 opens with a specific verb phrase 'Trigger immediate verification + SSL + nginx provisioning' and clarifies the target as 'a previously-added domain,' clearly distinguishing it from sibling tools like wafle_domains_add, wafle_domains_list, and wafle_domains_status. The numbered pipeline further concretizes the action.
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 states this is for 'previously-added domain' and highlights idempotency and a rate limit, giving the user clear context for when to invoke it. It does not explicitly name alternative tools (e.g., wafle_domains_status) or state when not to use it, so the guidance is solid but not fully explicit.
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?
Annotations already include destructiveHint=true, and the description reinforces and extends this by stating 'Destructive AND irreversible' and advising to 'Confirm amount before calling.' It also discloses the refund routes through the capturing gateway (MercadoPago/Stripe/manual transfer), adding beyond the structured data.
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?
Three short sentences, no filler; the core action is front-loaded and the safety warning follows naturally.
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 destructive refund operation, it conveys the essential action, scope, gateway, and irreversibility warning. It lacks an explicit pointer to wafle_checkout_order_refund, but overall it is complete enough to guide an agent, especially since no output schema exists.
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 itself documents slug and amount, including 'Omit for full refund; set for partial.' The description echoes the full/partial behavior but adds no new meaning for order_id or reason, which lack schema descriptions. Thus it contributes marginal value over the schema.
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 'Refund a paid order, fully or partially,' giving a specific verb and resource plus clarifying the full/partial scope, and distinguishes from order-cancellation tools. It doesn't explicitly mention the checkout_order_refund sibling but the intent is clear from the name and first sentence.
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 establishes when to use it: when a paid order needs a refund, and notes gateway routing. It does not name alternatives or state exclusions, so it provides clear context but stops short of explicit differentiation.
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?
The description adds behavioral nuance beyond the idempotentHint annotation by explaining the partial update and null-clearing semantics. It does not disclose potential side effects or permissions, but the idempotent hint reduces the need for extensive safety disclosure.
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 action, and every word adds value. 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?
The description fully covers the tool's purpose and key behavioral nuances for a simple mutation. No output schema exists, so return values are not required. It is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (40%) with only slug and meta described. The description compensates by explaining the core semantics of all pixel parameters: 'Pass only the pixels you want to change; omit fields stay untouched. Pass null to clear a pixel.' This adds crucial meaning to the nullable string fields.
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 states the tool's function with a specific verb ('Set / update') and resource ('marketing pixel IDs of a store'). It clearly distinguishes from the sibling wafle_pixels_get by focusing on mutation rather than retrieval.
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: only pass pixels to change, omit to keep, null to clear. It does not explicitly name alternatives (e.g., wafle_pixels_get), but the purpose is unambiguous and the partial-update semantics are actionable.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, establishing a safe read operation. The description adds value by specifying the exact metrics returned (pending/running/done/failed counts, throughput, lag) and the 'current' snapshot nature, which is useful behavioral context beyond the annotations.
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 core purpose, and every word adds value. The second sentence provides practical usage guidance without 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 zero parameters, comprehensive annotations, and a simple read-only operation, the description is complete enough. It states what the tool returns and when to use it. A brief note on how the stats relate to sibling queue tools (e.g., wafle_system_queue_failed) would enhance completeness, but it's not essential for this simple tool.
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 the input schema is trivially complete. The description correctly focuses on the return value, listing the statistics provided. With no parameters to explain, a baseline of 4 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 uses a specific verb ('Get') and resource ('background-queue stats'), and explicitly enumerates the metrics provided (pending/running/done/failed counts, throughput, lag). This clearly distinguishes it from sibling tools like wafle_system_queue_failed and wafle_system_queue_retry, which handle specific queue operations rather than an overview.
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 use cases: "debug 'why didn't my sync finish?' or to spot a backlog." This gives clear context for when to invoke the tool. However, it does not mention exclusions or alternatives, so it falls short of a full 5.
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?
Annotations already provide idempotentHint and destructiveHint, but the description adds concrete behavior: idempotent pausing returns ok=true, and it clarifies the auth model ('Uses the tenant's connected Meta access token; the LLM does not need to pass credentials'). It does not over-explain what annotations already cover, and adds useful specifics without contradiction.
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: the first states the action and idempotency, the second explains the auth model, and the third gives usage context and an alternative. Every sentence provides distinct, non-redundant value and is front-loaded.
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 two-parameter tool with good annotations, the description is complete: it covers what it does, the idempotent result, credential handling, when to use it, and when to prefer a sibling. No output schema exists, but the ok=true note gives sufficient response context.
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% and both parameters (slug, campaign_id) have clear descriptions with examples in the schema. The description adds no parameter-specific details beyond the schema, but also doesn't need to; 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 states a specific verb and resource: 'Pause a Meta Ads campaign by id.' It clearly distinguishes from sibling tools like wafle_ads_campaign_resume (resume) and wafle_ads_bulk_pause (multi-campaign), and the focus on a single campaign by id is explicit.
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?
Usage is explicitly guided: 'Use when ROAS is below threshold or as the apply step of a pause-recommendation.' It also names an alternative for multi-campaign cases: 'prefer `wafle_ads_bulk_pause` to avoid round-trip cost,' and the idempotency note clarifies when repeated calls are safe.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, and the description fully aligns with these. It adds substantial behavioral context beyond the annotations by detailing the return payload (spend, revenue, profit, ROAS, winning/losing campaigns, recommendations array), the underlying data source, and the month-aware aggregation layer. This is rich, non-redundant disclosure.
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 of core functionality plus one sentence of usage guidance and backend context. Each sentence earns its place; it is informative without bloat. The warning about not pasting raw JSON is valuable and concisely phrased.
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?
With no output schema, the description takes on the burden of explaining return values—it lists all expected fields. It also gives practical usage instructions for the narrative generation. For a report-generation tool with two well-documented parameters, this is complete and possibly exemplary.
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%: both 'slug' and 'month' are explained with examples in the input schema. The description adds little beyond that, but the schema already carries the full weight. Baseline 3 is appropriate because no compensation is 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 opens with 'Generate a structured monthly ads report for a store' and enumerates the exact metrics returned (total spend, revenue, profit, blended ROAS, top 5 winning campaigns, bottom 5 losing campaigns, recommendations). This clearly distinguishes it from sibling tools like wafle_ads_performance_summary or wafle_ads_compare_periods, which target different reporting needs.
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 explains that this is 'Designed as the input for Claude to author the executive narrative' and explicitly instructs not to paste raw JSON, instead rewriting into prose with recommendations as bullet points. It provides clear context for when this tool's output is appropriate, though it doesn't explicitly name alternative tools for different report types.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable context by specifying the structure of each returned entry (name, description, scope required, destructive flag, JSON Schema), which goes beyond what annotations provide. This helps the agent know what to expect from the output.
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 well-structured: two sentences, front-loaded with the main verb 'List', and no wasted words. It efficiently conveys purpose and output format.
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?
Given the tool has no parameters and no output schema, the description is complete: it explains what the tool returns (a catalog with specific fields) and its purpose. No additional context is needed for correct invocation.
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 the schema imposes no burden. The description does not need to explain parameters, and it effectively documents the output structure instead. This meets the baseline for a parameterless tool.
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 states a specific action ('List the catalog of tools') and a clear resource (tools that can be added to an agent's tools_allowed). It also outlines the contents of each entry, making it distinct from sibling tools like wafle_agents_list which likely list agents rather than the tool catalog.
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 this tool: to see what tools can be added to an agent's tools_allowed. It does not explicitly mention alternatives or exclusions, but the context is sufficient for an agent to understand the intended use case.
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 empty annotations, the description carries the burden. It discloses the return shape ('{ dsl_json, validated, errors }') and that this is a compilation step ('Pass dsl_json straight into a new segment'), implying it does not create the segment itself. It doesn't elaborate on error types, but the key transformation behavior is clear.
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 pack in the purpose, example, return object, and next-step guidance. No filler or redundant language; every clause earns its place and the key information is front-loaded.
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 two-parameter tool with no output schema, the description is complete: it explains inputs (with example), output structure, and the intended follow-up action. There are no significant gaps in understanding what the tool does or how to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by providing a concrete natural-language example and explaining how the output (`dsl_json`) should be used, which enriches the meaning of the second parameter beyond its schema description.
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 states a specific verb ('Compile') and resource ('natural-language description') into the 'email-marketing segmentation DSL', clearly distinguishing it from sibling AI tools like translate or categorize. It also explains the output ('dsl_json') and an example input, leaving no ambiguity about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear use case with a Spanish example and instructs to 'Pass dsl_json straight into a new segment', implying the workflow context. However, it does not explicitly mention when not to use or name alternatives, so it falls short of a 5.
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?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds value by detailing the return row fields (code, type, value, usage, validity dates, applies-to scope), which is not present in the schema or annotations. It stops short of noting pagination or caveats, but this is a simple list 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-loaded with the core purpose, then the return format, then a usage hint. Every sentence earns its place, with no redundancy.
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?
Despite having no output schema, the description compensates by listing the exact fields returned. With one clearly documented parameter, read-only annotations, and clear usage context, the tool is fully specified for an agent to invoke 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 coverage is 100% and the parameter description already explains the slug format and examples. The tool description only refers to 'store' without adding new details about the slug syntax or constraints, so it does not exceed 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?
Description states a specific verb ('List'), resource ('all coupons of a store'), and scope, distinguishing it from sibling coupon create/update/delete tools. The row content is also specified, 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use to audit active discounts or to find a code before editing' explicitly states when to use and gives context relative to editing actions. This differentiates it from write operations among sibling tools.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description correctly aligns. It adds valuable privacy/disclosure behavior: 'Secrets are NEVER returned (only `{set:true}` markers).' This goes beyond the annotations by explaining how sensitive data is handled, which is important for an agent deciding to invoke the 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-loaded with the main action, and every sentence earns its place: the first states the operation and key attributes, the second provides the use case and the crucial security note. No fluff or redundancy.
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?
Given no parameters, a rich annotation set, and no output schema, the description covers all essential aspects: the resource scope, the returned fields, the use case, and the critical secret-handling behavior. It is complete enough for an agent to select and invoke the tool correctly in most scenarios.
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 there is no parameter documentation burden. The description instead describes what the returned data includes (type, currency, active flag, store association), which adds some semantic value beyond the empty schema. This meets the baseline for a no-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States the action clearly: 'List all payment gateways across all stores (master view).' It specifies the resource (payment gateways), scope (all stores), and nature (master view), which differentiates it from create/delete/update/test siblings. The 'master view' phrase further distinguishes it from any store-specific listing tool.
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?
Provides explicit usage context: 'Use to audit which stores have which gateways configured.' This gives a clear when-to-use scenario. However, it does not explicitly mention alternatives or when not to use it, so it lacks the full exclusions/alternatives guidance that would earn a 5.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safe-read profile is established. The description adds value by listing the categories of rules returned and emphasizing the composability aspect, which is useful behavioral context beyond the annotations.
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, no fluff, front-loaded with purpose and rule types, followed by a practical usage note. Every word earns its place.
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?
Given the single parameter, strong annotations, and list-oriented nature, the description is complete: it states what's listed, when to use it, and why. The absence of an output schema is acceptable because the returned items are clearly implied as the pricing rules themselves.
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 only parameter 'slug' is fully described in the input schema with pattern and examples, giving 100% schema coverage. The description itself does not add parameter syntax or additional meaning, so it meets the baseline for schema-covered params.
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 ('List') and identifies the resource ('dynamic pricing rules of a store') while enumerating rule types (catalog-wide multipliers, category markups, etc.). This clearly distinguishes from sibling tools like wafle_pricing_rules_create, update, and delete.
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 explicitly states when to use it ('Use before editing') and explains why ('pricing rules compose, so you need to know what's already there'). This gives clear contextual guidance and implies alternatives (editing tools).
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?
Beyond the annotations (read only, idempotent), the description discloses that it returns a subset (settings) and explicitly excludes items/orders. This gives the agent valuable behavioral context about the response scope and the tool's relationship to the base getter.
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 sentence properly front-loaded with the core purpose, followed by scope and use case. Every word earns its place; no filler or repetition of schema/annotation names.
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 1-parameter tool with no output schema, the description sufficiently explains what is returned (settings subtree) and what is not (items/orders). Annotations confirm safety, so no missing behavioral critical for an agent to invoke 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 coverage is 100% for the single 'slug' parameter, including format and examples. The description adds no new parameter details, but the schema already fully documents the parameter. 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 clearly states it retrieves only the settings subtree of a store, distinguishing it from the broader wafle_stores_get and other store tools. The verb 'returning' and specific resource 'settings' make the purpose unambiguous. It also hints at intended use case (review/diff workflows).
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 identifies this as an alias of wafle_stores_get and scopes it to settings only, implying use when full store data is not needed. It mentions convenience for review/diff workflows, giving clear context, though it does not explicitly state when not to use it or compare with settings_update.
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?
Annotations already mark readOnlyHint and idempotentHint, so safety is covered. The description adds behavioral detail by specifying the exact checks (db/redis/upstream/WooCommerce) and that latency is returned per check, plus the cost implication of being a 'cheap' call.
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: one for scope and output, one for usage recommendation. Every word contributes. There is no fluff or repetition.
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 zero-parameter read-only health check, the description provides sufficient detail: components checked, return value (latency), and intended use. No output schema exists, but the simple output is adequately implied.
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?
There are zero parameters, and the schema has 100% coverage (trivially). The description doesn't need to explain parameters; it correctly focuses on behavior.
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 identifies the tool as a health snapshot of the wafle backend, listing specific components (db, redis, upstream catalog, WooCommerce core) and states it returns latency per check. This distinguishes it from sibling tools like wafle_system_stores_health and wafle_system_queue_stats.
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 advises using this as 'a cheap first call when something looks off in production,' giving clear diagnostic context. It doesn't enumerate alternatives, but the 'first call' phrasing implies a triage role.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. Description adds context about the exact contents (deployed versions of api, plugin, dashboard, themes) and the operational scenario, which goes beyond the annotations. No contradiction.
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 short sentences, front-loaded with the action and resource, then a usage note. Zero waste; every word adds value.
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 zero-parameter read-only list tool, the description fully explains what is listed (components) and why/when to use it (before deploy/rollback). Annotations cover safety, and no output schema is needed for such a simple listing.
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?
Tool has zero parameters; baseline is 4. Description adds no parameter-specific details, but none are needed. The schema coverage is 100% (vacuously), so the description does not need to compensate.
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?
Description clearly states 'List the deployed versions of every wafle component' with specific component enumeration (api, plugin, dashboard, themes). It names the exact resource and action, distinguishing it from deployment/rollback siblings.
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?
Explicitly says 'Use before deploying or rolling back', giving clear timing context. Does not mention alternatives, but siblings like 'wafle_system_release_deploy' and 'wafle_system_release_rollback' are implied. A clear usage directive without explicit exclusions merits a 4.
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?
Annotations already mark it read-only and idempotent. The description adds meaningful operational context: the session token requirement and the 401 failure mode for legacy API keys. It also reveals the return scope (profile, memberships, current tenant), which is extra value beyond annotations.
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 with front-loaded purpose. The first sentence states exactly what the tool returns; the second gives the critical auth requirement. No verbose or redundant content.
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 0-parameter, read-only identity endpoint, the description is complete: it covers purpose, return scope, authentication requirements, and failure conditions. The annotations are strong, and no output schema is needed given the described payload.
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?
There are zero parameters, so the baseline is 4. The description adds no parameter-specific semantics because none are needed; the empty schema is already fully described.
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 states 'Return the currently-authenticated human's profile + memberships + current tenant' — a specific verb+resource scope. The 'human' qualifier differentiates it from system-level auth or membership-only tools, and the annotation title reinforces the 'who am I' purpose.
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 the prerequisite: 'Requires a session token (WAFLE_USER_SESSION)' and gives a clear exclusion: 'Will fail with 401 if the MCP is using a legacy API key.' This tells the agent when the tool is appropriate, though it does not name alternative tools.
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?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is known. The description adds that it returns 'tenant's slug, name, role, and effective scopes' and clarifies 'current human', which is useful but not required given the annotations. No contradictions.
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 compact sentences. The first sentence states the primary function, and the second lists the return fields. Every word adds value, with 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?
This is a simple, zero-parameter read tool. The description fully covers what it does and what it returns. No output schema exists, but the return fields are enumerated, making the tool's behavior complete and understandable.
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?
There are zero parameters and schema coverage is 100%, so no parameter info is needed. Per rubric, 0 params gives a baseline of 4. The description reinforces that no input is required.
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 states the specific action 'List', the resource 'memberships', and the scope 'current human's across all tenants'. It clearly distinguishes from sibling tools like wafle_users_me (current user details) and wafle_members_list (members of a specific tenant). The return fields are specified, adding clarity.
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 implies usage context: to view a user's memberships across tenants, including roles and scopes. It does not explicitly mention alternatives or when-not-to-use, but the scope is clear. This is strong context without exclusions, earning a 4.
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 and discloses key behavioral traits: it reads product data, runs an LLM, creates a pending review job rather than directly modifying the product, and requires an accept step to apply changes. Also notes approximate length and tone options, providing clear expectations.
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 short paragraphs front-load the purpose and workflow, then provide parameter specifics. Every sentence contributes useful information without redundancy or 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?
The description explains the end-to-end behavior and side effects, but does not explicitly describe the return value (e.g., job ID or status), which would be helpful given the absence of an output schema. Still, the workflow is clear enough for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers sku, slug, and locale explicitly. The description adds meaning for the undocumented parameters ton and length_words: tone is listed as 'persuasivo' | 'tecnico' | 'breve', and length is described as approximate words (±15%), complementing the schema's defaults and constraints.
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 'Generate a sales copy description for a product' and outlines the full workflow: reads catalog data, runs the configured LLM, and stores output as a pending review job. This distinguishes it from sibling tools like wafle_ai_categorize and wafle_ai_translate.
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?
Provides clear context for when to use this tool (generating sales copy) and explains the follow-up action (call wafle_ai_jobs_accept to apply). It does not explicitly mention alternative tools or exclusions, but the purpose is specific enough to avoid confusion.
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?
Beyond the idempotentHint annotation, the description discloses that overrides survive catalog syncs, are stored server-side, and are re-applied after every sync. This gives the agent critical behavioral context for what might otherwise seem like a simple mutation.
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 short paragraphs; the first sentence states the purpose, the second gives usage guidance, and the final sentence explains persistence. Every sentence carries weight, and the key information is front-loaded.
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 description covers what the tool does, when to use it, and its persistence behavior. Since there is no output schema, explaining return values is unnecessary. It could additionally clarify whether overrides merge or replace existing fields, but the description is sufficient for the tool's simple scope.
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 description adds meaning to the 'overrides' parameter by listing example fields (price, name, description, images), which is not in the schema. Slug and product_id are reasonably clear from their schema definitions or context, but product_id lacks explicit description; overall the description adds value beyond the schema.
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 'Set' and resource 'per-product overrides' with explicit fields (price, name, description, images). It distinguishes from sibling tools like wafle_products_update by emphasizing persistence across catalog syncs.
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 states when to use: 'Use on supabase_sync stores when you need to tweak a single product without forking the whole catalog.' This provides clear context and implies alternatives, though it doesn't explicitly enumerate when not to use it.
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?
The description discloses key behavioral traits beyond annotations, including the blocking wait behavior, the 5-minute timeout, and the emission of MCP progress notifications. Annotations only indicate idempotent=false and destructive=false, so the description adds significant context about the tool's runtime 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 efficiently structured with two clear sentences: the first explains the tool's core behavior, and the second provides usage context and alternatives. Every sentence earns its place with no redundant information.
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 description covers the main purpose, usage, blocking behavior, and alternative tools, making it largely complete. However, it does not clarify what happens on timeout (e.g., whether it returns an error or a partial result), which could be relevant for an agent deciding whether to call this 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 description coverage is 67% (slug and timeout_seconds are described, mode is not). The tool description does not add new meaning for the parameters beyond what the schema provides; it only reinforces the timeout default. The `mode` parameter remains under-explained, but the enum values are relatively self-explanatory.
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 triggers a catalog sync and waits for completion (or timeout), using a specific verb and resource. It also distinguishes itself from the sibling tool `wafle_products_sync_trigger` by naming the alternative for fire-and-forget behavior.
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 on when to use this tool ('use when the LLM wants to take an action after the sync is done') and when not to use it, explicitly naming `wafle_products_sync_trigger` as the alternative for fire-and-forget use.
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?
Annotations declare readOnlyHint and idempotentHint, so the read-only nature is already known. The description adds important behavioral context: Meta's API is sampled and stale by hours, results are cached for 6 hours per tuple, and the matrix auto-picks audiences based on min_size. This goes beyond annotations and helps set expectations.
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?
Three sentences plus a note, front-loaded with purpose and output. Every sentence adds value: output definition, when to use, parameter behavior, and data freshness caveat. No filler or repetition of schema details.
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?
Given no output schema, the description fully covers the return shape, input semantics, sampling/caching behavior, and a practical interpretation. It is a complete enough description for an AI agent to effectively select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already provides descriptions for all three parameters (100% coverage), so baseline is 3. The description adds semantic value by explaining that omitting audience_ids triggers auto-picking of audiences above min_size, and that audience_ids can 'limit the matrix'. This clarifies the relationship between parameters better than the schema alone.
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?
Description begins with a specific verb and resource ('Compute % overlap between custom audiences') and clearly states the output (matrix of overlap_pct + overlap_users). It is distinct from sibling tools like wafle_ads_compare_periods or wafle_ads_breakdown_by_creative, which focus on other ad metrics.
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?
Explicitly says 'Use this when the merchant runs many similar adsets' and provides a threshold (>40%) with interpretation. It also explains when to pass specific audience_ids versus omit them. It does not name alternative tools, but the use-case guidance is clear.
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?
Beyond the annotations (readOnlyHint, idempotentHint), the description powerfully discloses behavioral details: the ROAS is derived from CAPI server-side truth rather than Meta pixel, the `winner` flag logic (top quartile ROAS AND spend above floor), and the default significance floor of 5,000 cents. This enriches the agent's understanding of how results are computed and interpreted, far exceeding the annotation safety hints.
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 compact yet thorough: the first sentence captures the core purpose and return metrics; the second adds the unique data-source qualification; the second paragraph gives the use case, default sort, and winner-flag algorithm. Every sentence earns its place with no filler or repetition.
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?
There is no output schema, so the description must explain what the tool returns and key behaviors—it does both thoroughly, covering metrics, ROAS source, winner flag, and significance threshold. For a read-only breakdown tool with 5 parameters, this fully equips an agent to understand the tool's purpose, output, and parameter implications.
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 already covers most parameters (80% description coverage). The description adds meaning by explaining the significance floor (min_spend_cents default) and the default sort behavior, while the winner-flag explanation ties parameters to output semantics. This goes beyond the schema's dry descriptions and justifies a score above the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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+resource ('Per-creative performance breakdown') and states exact metrics returned (spend, impressions, clicks, conversions, ROAS, CPA). It also distinguishes itself from siblings by clarifying scope (campaign or account-wide) and its unique CAPI cross-tabbing, making it unmistakable from tools like wafle_ads_performance_summary.
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 provides an explicit use case: 'Use when you need to find the *one* creative carrying a campaign vs the ones bleeding spend.' While it doesn't name alternative tools or state when-not-to-use, the scenario is clear and the differentiator (CAPI truth, winner flag) guides selection.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context by stating that there are exactly 5 templates and listing them, which goes beyond the annotations. It doesn't contradict the annotations.
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, immediately starts with the verb and object, and every word earns its place. It lists all five templates compactly and then gives the usage pointer. No redundant formatting 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 zero-parameter, no-output-schema tool with strong annotations, the description fully covers what the agent needs: the exact templates available and how to consume them. There is no missing behavioral or contextual information.
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 takes zero parameters, so there is no schema to clarify. The rule for 0 params gives a baseline of 4; the description doesn't need to add parameter info. It doesn't mislead about any inputs.
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 action ('List') and the resource ('5 pre-armed agent templates'), and even enumerates the exact templates. This fully distinguishes it from sibling tools like wafle_agents_list (which lists actual agents, not templates) and wafle_agents_create (which creates agents).
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 explicitly tells the agent how to use the result: 'Use the `id` field as `from_template` in `wafle_agents_create`.' This provides a direct, actionable usage guideline. While it doesn't contrast with alternatives, the instruction is clear enough and the context of sibling tools fills in the rest.
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?
Discloses a critical behavioral trait: the secret is returned only once and must be stored immediately. Also warns about potential backend unimplemented endpoint and upstream error propagation. Annotations are sparse (no readOnlyHint, but idempotentHint false is consistent with creation). The description adds significant value beyond structured fields.
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 compact and well-structured: main purpose and critical warning in the first sentence, usage context second, backend caveat third, access control fourth. Every sentence serves a distinct purpose without fluff, making it highly readable and actionable.
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 credential-creation tool with no output schema, the description covers all necessary context: security (secret-once), access control (admin-only), usage scenarios, and error behavior. It is complete for the tool's complexity and complements the schema and annotations well.
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 schema already documents all parameters. The description adds minimal parameter-specific meaning (e.g., 'given scopes' is redundant, but 'Prefer narrowly-scoped keys' gives usage guidance for scopes). Baseline 3 is appropriate; no additional parameter semantics provided.
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 ('Create a new wafle API key') with a specific resource and required scopes, distinguishing it from sibling tools like wafle_auth_keys_list. The verb+resource pattern is explicit 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use context ('onboarding a new dashboard user, integration, or agent'), recommends best practice ('Prefer narrowly-scoped keys'), and clearly states an exclusion ('Admin-only: tenant clients cannot mint API keys'). This gives the agent strong guidance on invocation.
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?
Beyond the readOnlyHint and idempotentHint annotations, the description adds critical behavioral context: 'Full secrets are NEVER returned,' 'tenant clients cannot enumerate,' and the conditional store filter ('if the upstream key supports it'). These disclose permission boundaries and output limitations not captured by annotations.
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 well-structured: the first sentence states the primary purpose, the second explains return format and a key safety guarantee, and the third gives an access restriction. Every sentence adds value with no redundancy.
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?
Given that there is no output schema, the description adequately explains the return value (prefix + scopes) and that secrets are never returned. It also covers access restrictions and the optional store filter behavior. For a simple one-parameter read tool, this is 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 schema already documents store_slug with 100% coverage ('Optional: filter to keys scoped to this store'). The description adds the caveat 'if the upstream key supports it,' explaining that store filtering may not always be available. This is meaningful extra context beyond the schema, raising the score above the baseline 3.
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 verb and resource: 'List API keys associated with the master account' with an optional store filter. It also distinguishes from siblings by specifying the return of prefix+scopes and prohibiting full secrets, making it distinct from key creation or auth info tools.
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 a clear use case: 'Use to audit who has access.' It also states an explicit exclusion: 'Admin-only: tenant clients cannot enumerate API keys.' However, it does not name alternative tools for when this tool should not be used, so it falls short of a 5.
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?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds value beyond annotations by specifying the exact response shape (`{ ok: true, type: 'master' | 'store', store_slug?, scopes? }`) and clarifying its scope (admin key, not user auth). This is good context for an otherwise simple read 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?
Three tightly written sentences: the main purpose, a usage scenario, and a critical limitation. No redundancy or filler. The key 'Do NOT use' warning is front and center where it matters.
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 no-parameter, read-only diagnostic tool, the description fully covers purpose, usage, expected output shape, and exclusions. With no output schema, the description compensates by documenting the return object. Sibling tools are numerous, but this tool's scope is simple and completely specified.
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 the schema is 100% covered by 'No parameters.' Per the baseline for 0-param tools, a score of 4 is appropriate. The description adds no parameter details because there are none, but it does not need to.
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 returns information about the configured wafle admin key for the MCP server, with the specific verb 'Return information about'. This distinguishes it from siblings like wafle_users_me (user info) and wafle_auth_keys_create/list (key management).
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 tells the agent when to use it ('to verify the server is correctly authenticated before running other tools, or to debug a 401 error') and when NOT to use it ('Do NOT use this to authenticate end-user requests'), even pointing to the separate magic-link auth. This is exemplary 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?
Annotations already declare readOnlyHint and idempotentHint. The description adds that it returns 'base price, applied rules, final price', which is useful behavioral context given no output schema. It also reinforces non-destructive behavior in operational terms ('without disturbing the live cart').
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, with the action and inputs front-loaded. The second sentence provides practical usage context. No filler or redundant information.
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?
Given simple parameters, strong annotations, and no output schema, the description covers purpose, inputs, outputs, and use case adequately. It is complete enough for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, with slug described but items not. The description clarifies items as 'a list of (sku, qty) pairs', adding meaning beyond the schema. It does not fully explain qty constraints, but the schema still provides defaults and bounds.
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 ('Compute') and resource ('final price of a list of (sku, qty) pairs'), clearly distinguishing it from pricing rules management siblings. It also states the role as a preview/sanity check tool.
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 says 'Use as a sanity check before publishing pricing changes' and notes it 'answers how much would I be charging? without disturbing the live cart', which gives both a clear use case and an exclusion (not for live operations).
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?
Annotations already indicate idempotentHint and destructiveHint, but the description adds valuable context: substring matching behavior, flushing behavior, and the effect on subsequent reads. It also discloses the 'Master only' permission requirement, which is not present in annotations. No contradiction with annotations.
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 action, and every sentence earns its place. The first sentence covers the core function and parameter semantics; the second covers usage context and permission. No waste or repetition.
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, no output schema, and helpful annotations, the description is fully complete. It explains the operation, the parameter's effect, when to use it, and a master-only constraint. No gaps remain for the agent to infer.
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 restates the parameter behavior ('Pass uri_pattern to drop matching entries (substring match), or omit to flush everything') but adds no new parameter-level details beyond what the schema already provides. The 'Master only' note is tool-level, not parameter-level.
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 action: 'Invalidate the in-memory MCP resource cache,' with a specific verb and resource. It also explains the optional parameter behavior and distinguishes this from sibling tools by focusing on cache invalidation, which no other tool addresses.
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 states when to use the tool: 'Use after a destructive write (mutating products, settings) if you want the next resources/read to fetch fresh data.' It also adds the 'Master only' restriction, providing clear context for invocation relative to alternatives.
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?
Annotations already declare readOnlyHint and idempotentHint. The description adds useful context: the security scoping ('configured key can see'), the admin-only restriction for tenant-level MCP, and the specific fields included in the response. This goes beyond the annotations without contradicting them.
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 compact and front-loaded with the core purpose. The first sentence immediately explains what the tool does; the following sentences add high-value usage guidance and an access caveat. Every sentence earns its place with no redundancy.
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?
Despite having no output schema, the description enumerates the response fields (id, slug, name, domain, brand color, payment/shipping config, gateway IDs, contacts), making the return format clear. With zero parameters, mature annotations, and explicit usage/admin notes, the description is fully adequate.
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, and the schema explicitly states 'No parameters.' with 100% coverage. The description doesn't add parameter details because none exist. The baseline for 0 parameters is 4, and nothing in the description detracts from that.
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 states a specific action ('List all wafle stores') and a clear scope ('the configured key can see'), and lists the key fields returned. It distinguishes from sibling tools like wafle_stores_get (single store) and wafle_stores_create by focusing on listing all accessible stores.
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 says to use this as the first call for store-related questions and before any per-store action because the slug is needed. It also contrasts with wafle_stores_get for per-tenant MCP clients, providing clear when-to-use and alternative guidance.
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?
While the destructiveHint annotation already flags danger, the description adds critical behavior context: it 'touches production', requires user confirmation, and kicks off a server-side pipeline. This goes beyond the annotation and helps the agent understand the real-world impact.
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 tight sentences: the first states purpose, the second warns of danger and gives steps. Every word earns its place, with 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 destructive deploy tool with two well-documented params and no output schema, the description covers purpose, safety, prerequisite steps, and alternatives. It is sufficiently complete for an agent to decide whether and how 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 100%, with descriptions for both 'version' and 'component' providing examples. The tool description itself adds no additional parameter semantics, so it relies on the schema; 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 'Deploy a specific version of a component' with a specific verb and resource, distinguishing it from siblings like wafle_system_release_rollback and wafle_system_versions_list. It unambiguously conveys the action and target.
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 usage guidance: confirm with the user, run wafle_system_versions_list first, and prefer staging if available. This tells the agent when and how to use the tool, and offers an alternative approach (staging).
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?
Annotations already establish read-only and idempotent behavior. The description adds that this operation is heavier than wafle_system_health, providing useful context about performance/cost. It does not detail return format, but annotations lower the baseline; this is sufficient.
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 short, information-dense sentences with no 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 parameterless health read, the description fully specifies what the tool covers (products, orders, errors, gateway connectivity) and its relation to the sibling tool. No output schema exists, but the listed metrics imply the response contents.
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?
There are zero parameters, so the baseline is 4. The description does not need to elaborate on parameters.
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 specifies that the tool reports per-store health metrics (products count, orders in the last 24 hours, errors, gateway connectivity), clearly distinguishing it from wafle_system_health by noting it is heavier. This provides a specific resource and scope, earning a 5.
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 compares to wafle_system_health (used for lighter health checks) and lists the detailed metrics available here, helping the agent choose the appropriate tool. The mention of an alternative satisfies the 'when/when-not' criterion.
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?
Annotations already mark the tool as readOnly and idempotent. The description adds behavioral context with 'This tool NEVER mutates' and explains the recommendation logic (distance below threshold, Learning Phase status, trend vs previous period). It also discloses that output is shaped for direct pasting into follow-up tool calls, which is valuable for the agent's decision-making.
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 well-structured paragraphs. The first sentence states purpose and scope; the second clarifies the non-mutating nature and execution path; the third explains the recommendation logic. Every sentence earns its place with no redundancy or 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?
With no output schema, the description must explain returns. It states the tool returns a list of adsets with recommendations and ids for follow-up, and explains the recommendation basis. While it doesn't enumerate every return field, its focus on LLM-friendly output and integration with sibling execution tools makes the description sufficiently complete for the tool's proposing role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description enhances parameter understanding by integrating `threshold_roas`, `min_spend_cents`, and `range` into the tool's core filtering logic, showing how they combine to trigger recommendations. It does not add new parameter-level details, but the contextual integration adds meaningful value.
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 'READ-ONLY proposer' and clearly states it returns a list of adsets filtered by ROAS and spend criteria, with per-item recommendations. It distinguishes itself from execution tools by naming `wafle_ads_campaign_pause`, `wafle_ads_bulk_pause`, and `wafle_ads_campaign_update_budget` as the required follow-up actions.
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 says 'This tool NEVER mutates' and instructs that to execute, the caller must call the named execution tools with the returned ids. This provides clear when-to-use guidance and explicitly names alternatives, telling the agent the exact sequence of tool invocation.
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:

[![wafle-mcp MCP server](https://glama.ai/mcp/servers/the33warehouse-tech/wafle-mcp/badges/card.svg)](https://glama.ai/mcp/servers/the33warehouse-tech/wafle-mcp)

Score Badge

Copy to your README.md:

[![wafle-mcp MCP server](https://glama.ai/mcp/servers/the33warehouse-tech/wafle-mcp/badges/score.svg)](https://glama.ai/mcp/servers/the33warehouse-tech/wafle-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/the33warehouse-tech/wafle-mcp'

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