Firestarter MCP Server

Server Quality Checklist

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

Latest release: v2.15.0
Disambiguation3/5
Long descriptions do a lot of work to separate closely related tools, but several names genuinely overlap in purpose: firestarter_execute vs firestarter_preview, firestarter_list vs firestarter_listings, firestarter_watch vs firestarter_watches, and the family of firestarter_*drop* tools. An agent could easily pick the wrong one without carefully reading the detailed descriptions.
Naming Consistency3/5
Most tools follow a clear firestarter_verb_noun pattern, but there are many exceptions: bare verbs (check, execute, reprice), plain nouns (status, receipt, payouts), and confusing singular/plural pairs (watch/watches, list/listings, my_market/my_markets). No camelCase or other conventions, so it's still readable, but the pattern is far from uniform.
Tool Count1/5
At 89 tools, this is an extreme count for any single server. Even a multi-faceted marketplace platform would be better split into buyer, seller, and community-focused servers. The sheer volume makes it hard for an agent to navigate and select efficiently.
Completeness4/5
The tool surface is remarkably complete across buyer purchasing, seller fulfillment, community markets, drops, wallets, and payments. Minor gaps exist—there is no address update/delete, no seller response to reviews, and no explicit tool to update a saved address—but these are edge cases agents can work around.
Average 4.5/5 across 89 of 89 tools scored. Lowest: 3.5/5.
See the Tool Scores section below for per-tool breakdowns.
- 1 of 1 community issues answered or closed in the last 6 months
- 352 commits in the last 12 weeks
- Last stable release on August 26, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
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

Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, and the description reinforces this by stating the action dispatches a real crew and charges a fee. It also adds detail about the escrow inspection window when linked to a purchase execution, providing useful side-effect context beyond the annotations. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each serving a purpose: stating the action, highlighting the real-world consequences and prerequisite, and describing a side effect. It front-loads the main action and is efficiently written without redundancy. It is concise and well-ordered.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 11 parameters, no output schema, and low schema coverage, the description leaves significant gaps. It doesn't mention what the booking returns (e.g., a booking ID), how errors are reported, or the format for addresses and contacts. While it explains the relationship to quotes and execution, it's incomplete for an agent to confidently construct a valid call with all required fields.
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 only 36% schema description coverage, the description should compensate by explaining key parameters, but it only lightly touches on quote_ref and provider. It mentions the 'exact quoted price' but doesn't explicitly map it to fee_cents, and leaves required params like pickup_address and dropoff_address unexplained beyond their names. The description adds some meaning but fails to fill the coverage gap for most of the 11 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 clearly states the primary action: 'Book a courier from a firestarter_assist_quote result.' It specifies the resource (courier) and the source (quote result), and distinguishes it from sibling tools like firestarter_confirm_delivery by focusing on the booking action. It could be more explicit about the distinction from other shipping tools, but the purpose 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides critical usage guidance: it dispatches a real crew, charges the buyer's order, and requires prior explicit confirmation of the quoted price. This tells the agent when it's appropriate to call the tool and what prerequisites must be met. It doesn't explicitly state alternatives, but it implies this is a post-quote, post-confirmation step, which is sufficient for distinguishing it from quote-generation 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 indicate destructive and non-read-only behavior. The description adds useful context beyond that: it specifies a soft delete, states that buyers' agents can no longer find or buy the product, and notes that the share link goes dark. It does not disclose reversibility or permission requirements, but with annotations present, the added behavioral detail is strong.
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 filler. The verb and resource are front-loaded in the first phrase, followed by a clear consequence. Every sentence contributes useful behavioral 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 single-parameter mutation tool with annotations and no output schema, the description is largely complete: it names the resource, the action, the soft-delete nature, and the immediate visible effects. It lacks only minor details like return behavior or whether the action is reversible, but those are not critical for invoking 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?
The schema already documents the only parameter (listing_id) with 100% coverage. The description adds the 'your listings' ownership nuance, but does not expand on the parameter format beyond what the schema provides. Baseline 3 is appropriate since 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.
Purpose4/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: 'Remove one of your listings from the network'. It also clarifies the semantic of a soft delete, which is more specific than just 'delete' and distinguishes it from other listing-related operations. It does not explicitly name a sibling alternative, but the resource and effect are clear enough to identify this as the delist tool.
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 explains what the tool does and the immediate market effect, but it does not provide explicit guidance on when to use this tool versus alternatives such as updating a listing, canceling an order, or deleting a ship-from location. No when-not-to-use conditions or alternative tool names are given.
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 destructiveHint=false, so the safety profile is covered. The description adds some useful context about what the tool returns (last check status, recent price changes, alerts), but it does not disclose behavioral details like pagination, result limits, or how 'recent' is defined.
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 primary action is front-loaded, and the supporting detail about what the list shows is compact and directly useful. 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 list tool with two optional parameters and no output schema, the description covers the essential return content: active monitors, last check status, price changes, and alerts. It could be more explicit about filtering via monitor_id or the include_checks default, but those are already documented in the schema, so the description is adequately 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 100%, so both monitor_id and include_checks are already well documented in the input schema. The description adds no additional meaning about these parameters, 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 opens with a specific verb and resource: 'List active monitors and their recent check results.' It clearly states the tool's scope (active monitors) and what it surfaces (last check status, price changes, alerts), distinguishing it from sibling tools like firestarter_watch or firestarter_unwatch without needing to name them.
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 implies the tool is for viewing monitors but gives no explicit guidance on when to use it versus alternatives, no prerequisites, and no exclusions. With many sibling tools like firestarter_check, firestarter_status, and firestarter_watch, more routing context would help an agent select this tool confidently.
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 destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: the scope is restricted to markets the user owns, and the output includes earnings pending vs paid out and transaction counts. It does not describe auth, response structure, or edge cases, but with annotations present 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and mostly front-loaded, but the phrase 'override earnings pending vs paid out' is awkward and likely a typo for 'overview'. It does not parse cleanly, which hurts clarity. Aside from that, 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 no-parameter, read-only tool with no output schema, the description provides the key information an agent needs: the target resource, the data categories, and the typical user trigger. It does not spell out exact return field names, but the description names enough to make invocation and interpretation feasible.
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 100% schema description coverage, so there is nothing for the description to clarify about parameters. With no params, the baseline is 4; the description appropriately focuses on the tool's output rather than inputs.
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 specific verb ('Show'), a clear resource ('earnings of the markets you own'), and enumerates the data categories shown (pending vs paid out, transaction counts). It distinguishes the tool from siblings like my_markets and payouts, though it does not explicitly name them. The odd 'override' phrasing slightly reduces 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 explicitly says when to use this tool: when a community owner asks how much they have earned or wants their attribution dashboard. It does not list alternatives or when-not-to-use, but the context is clear enough for an agent to select this tool over unrelated 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?
The annotation destructiveHint=true already signals side effects, and the description adds concrete details ('creates a return shipping label and processes the refund'), going beyond the annotation. It does not mention irreversibility or additional consequences (e.g., restocking), but the combination of annotation and description is reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action and key effects, with a clear usage directive. No fluff or 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?
With only two parameters and no output schema, the description captures the essential behavior. However, it does not mention what the tool returns (e.g., confirmation, tracking number) or any prerequisites (e.g., payment status), leaving some ambiguity for an agent that needs to 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?
Both parameters (execution_id and reason) are fully documented in the JSON schema, so the description does not need to repeat their semantics. The description adds no parameter-specific guidance beyond what the schema provides, which is acceptable given 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the primary verb ('Initiate a return') and the resource ('purchased order'), and specifies the two main effects: creating a return shipping label and processing a refund. It is distinguishable from sibling tools like firestarter_cancel, though it does not explicitly call out 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit triggers ('Use when a buyer wants to return an item, get a refund, or reports a problem'), which gives an agent a clear condition to select this tool. However, it does not contrast with alternatives like firestarter_cancel or firestarter_disputes, so the agent must infer differences from the names alone.
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 indicate this is a write (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds the webhook notification behavior and the trigger conditions (price drops, restock, new listings), which is useful beyond annotations. However, it does not disclose side effects like persistence, whether the monitor can be modified, or any rate limits. The added context is helpful but not comprehensive.
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 primary action and then explains the notification behaviors. Every phrase contributes meaning without redundancy, making it highly scannable and efficient for an agent reading it quickly.
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 six parameters and no output schema, the description covers the core purpose and notification triggers, but it omits details like the default schedule, how the 'goal' parameter differs from 'query', and the fact that monitors are persistent and can be listed/canceled via sibling tools. The schema fills some gaps, but the description could be more complete in orienting the agent about the overall monitor lifecycle.
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 six parameters are already documented. The description does not add any explanation of how parameters relate to each other (e.g., goal vs. query) or provide usage nuances. Per the calibration, baseline 3 applies when the schema fully covers parameters and the description adds no extra value, which is the case here.
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 (create), the resource (price/stock monitor), and the core behavior (watches products on a schedule, notifies via webhook). It is distinct from sibling tools like firestarter_watches (list) and firestarter_unwatch (remove), and the title reinforces this. The verb+resource combination is specific enough for an agent to understand it creates a new monitor.
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 it (to set up a monitor) but does not explicitly mention alternatives or conditions for not using it. It relies on the agent inferring that creation is different from listing or removing monitors. There is no explicit guidance on when to prefer this over other sibling tools, though the purpose is clear enough that a capable agent would make the right call.
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 carry the safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower; the description adds value beyond them by disclosing what insights surface (buyer search terms, demand trends, pricing signals). This gives the agent an accurate sense of the response content without contradicting the read-only contract.
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 front-loaded sentences with zero filler: the first names the action and scope, the second elaborates the observable data. Every word earns its place and the most decision-relevant info leads.
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 tool with two optional parameters and no output schema obligation, the description covers purpose, scope, and data variety. The one gap is the zero-argument call: since no parameters are required, the behavior of the bare call is never clarified, which for a demand-check tool could be material.
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 fully documents both parameters and the baseline is 3. The description adds conceptual color about demand data but no parameter-level syntax or format details beyond what the schema provides. This is a fair baseline score with no penalty and no bonus.
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 ('Check') and a clear resource ('demand intelligence' for 'a specific listing or category'), and elaborates with concrete data types ('buyers are searching for, demand trends, and pricing signals'). It's not a tautology and clearly distinguishable from most of the ~100 siblings, though it doesn't explicitly name which sibling it is not versus, for example, seller_analytics or catalog_search.
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 phrase 'for a specific listing or category' implies when to use the tool and maps to the two parameters, but there are no explicit exclusions or alternative-routing cues despite a large sibling set where confusion is possible (e.g., firestarter_check, firestarter_seller_analytics). The usage context is inferable but never made 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 mark destructiveHint=true and idempotentHint=true. The description adds genuine value by spelling out the reversibility distinction—pause preserves history while delete does not—and explicitly flags the permanence of deletion. It's consistent with the annotations (no contradiction) and adds the historical-checks nuance that annotations can't express.
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 crisp sentences, front-loaded with the core verb and resource, with the critical consequence (permanence) placed for emphasis. Every word earns its place; no verification or redundant restatement of the tool name.
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 only 2 required params, full schema coverage, and no output schema, the description covers the essential lifecycle semantics well. The one minor gap: it never explains why 'resume' lives in an 'unwatch' tool or how resume relates to the watch flow, which could briefly confuse an agent, but nothing critical to invoking the tool is missing.
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 both parameters thoroughly, including the action enum with its own descriptions. The description adds context about pause/delete permanence but doesn't add a meaningful layer of param-level meaning beyond what the schema provides, so baseline 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 uses a specific verb-resource pair ('Pause or delete a monitor') and clearly distinguishes two modes of operation. It clearly differentiates from sibling tools like firestarter_watch and firestarter_delete_ship_from, though it does not name them explicitly.
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 the consequence of each action ('Paused can be resumed later; deleted are permanent'), which implies when to choose pause over delete. However, it never points to an alternative tool or states when NOT to use this tool, and the 'resume' action is only implied by the second sentence rather than given explicit when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and destructiveHint=false, but description provides no behavioral details beyond the semantic value. It doesn't state whether this is reversible, whether it affects the customer's eligibility retroactively, whether it triggers any notifications, or whether setting shares_required to a non-zero value effectively 'un-waives'. With zero annotation depth and a mutation tool, the description carries the full burden and comes up short.
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 verb and purpose, followed by a concrete example. Every word earns its place. No filler, no redundancy with schema.
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 single-purpose toggle tool with only two params)Skip. The schema and description together convey what parameters to set. What's missing: what happens after waiving (does the customer get benefits immediately? can it be undone?), and any side effects beyond eligibility. With no output schema and sparse annotations, a bit more behavioral context would help, but the tool is simple enough that 3 is fair.
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 baseline is 3. The description adds meaningful context to the shares_required parameter by explaining that 0 is the waiving value and that this applies per customer. It also clarifies the customer identifier format implicitly ('customer_...'). This goes beyond raw schema descriptions, though it doesn't fully explain edge cases like negative values (schema doesn't constrain minimum).
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 starts with a precise verb (waive) + resource (share requirement) and specifies the scope (for a given customer). It names the mechanism (setting shares_required to 0) and is distinct from siblings like apply_share_rule or remove_share_rule, which the described behavior clearly demarcates.
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 explains what waiving means (sets share requirement to 0) and gives a concrete example usage. It implies this is a per-customer override distinct from global rules, but it doesn't explicitly tell the agent when to prefer this over apply_share_rule or remove_share_rule. A short 'use this instead of X when...' would make it 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 indicate this is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds context about what the message can accomplish (refine, change, ask), which is useful but does not disclose any additional behavioral traits like side effects or idempotency. Given annotations cover safety, a 3 is fair.
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 zero fluff. It front-loads the primary action ('Send a follow-up message') and then lists concrete examples of usage. 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 messaging tool with no output schema and only two parameters, the description covers purpose and usage sufficiently. It doesn't explain what happens after sending (e.g., response format), but that is not critical for a follow-up message tool. The description is complete enough 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%: both parameters (execution_id, message) have descriptions. The tool description adds no extra parameter semantics, but the schema already documents them fully, so the baseline of 3 applies. No compensatory information 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 states a clear verb and resource: 'Send a follow-up message to an active execution.' It also enumerates the specific use cases (refine search, change requirements, ask questions), making the tool's purpose unambiguous and distinct from siblings that handle other execution-related actions. No sibling differentiation is needed since the purpose is self-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?
The description explicitly tells when to use the tool ('refine the search, change requirements, or ask questions about the options'). It doesn't mention when not to use it or name alternatives, but the context is clear given the broader workflow. The lack of exclusions is a minor gap, so a 4 is appropriate.
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 annotation declares readOnlyHint=true, yet the description says 'Pass refresh: true to re-fetch live carrier rates and persist them before showing the menu.' Persisting data is a write side effect, contradicting the read-only claim. Even though the rest of the description gives useful preview/no-purchase clarification, the contradiction forces a score of 1.
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 dense and front-loaded, but it has slight redundancy, such as 'preview before paying' and later 'Does NOT select or pay — it's a preview' and twice describing the returned. It is still a well-structured, useful text; just a bit longer than strictly necessary.
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 tool with no output schema, the description thoroughly explains the return value (numbered Delivery Options menu), how to advance from a menu number to firestarter_approve, when to use select_index, refresh for live rates, and the two main sibling alternatives. It covers all the important contextual decisions an agent would face.
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 has 100% coverage with meaningful descriptions for all parameters. The description adds value beyond that by explicitly connecting the numbered menu to firestarter_approve's shipping_option_index, clarifying why select_index is used for a preview, and noting that refresh may be used when the quote appears stale. This goes farther than simply restating 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 states a specific verb ('Show and compare'), a specific resource ('delivery speeds for an order awaiting approval'), and a precise preview action ('preview the re-priced total for a chosen speed'). It also explains the output contract (numbered menu, shipping_option_index) and differentiates it from firestarter_execute and firestarter_shipping_estimate, so the agent can distinguish it from siblings.
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 for delivery speed/cost questions, faster delivery wishes, or speed/price trade-off questions. It also gives exclusions and alternatives: firestarter_execute already lists options inline, approving without a pick uses the cheapest rate, and firestarter_shipping_estimate is for listings without execution.
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 only signal destructiveHint=true, readOnlyHint=false, and openWorldHint=true. The description does the heavy lifting: it discloses that shipping is deprecated and always estimated live, that re-firing the verification gate can trip on a price CUT, that it applies to paused/out-of-stock listings, that the listing is moved to draft and stops being buyable, and that the response is a conditional success. This precisely matches and greatly enriches the destructiveHint annotation — 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and long, but every clause earns its place — the verification-gate thresholds ($500, luxury category), the price-cut edge case, the paused/out-of-stock scope, and the conditional-success outcome are all decision-critical for an agent. Purpose is front-loaded before the caveats, so the most important information appears first. Slightly verbose, but not wasteful.
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 6-param mutation tool with no output schema but high behavioral complexity, the description covers the purpose, the destructive consequences, the trigger thresholds, and the response semantics fully. The only gap is procedural guidance on valid parameter combinations (whether listing_id alone suffices and whether price fields are mutually required), which the schema leaves implicit. No output schema means the agent must infer return shape, but the description's dovetailing with annotations keeps it nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all six parameters are already documented. The description adds some value by clarifying that 'shipping' is deprecated and ignored, and by tying base/floor/ceiling/dynamic_pricing to their intended effects. But it adds no syntax, units, or format details beyond the schema, and doesn't clarify which parameter combinations are valid (e.g., must at least one price field be supplied along with listing_id). Baseline 3 is appropriate when the schema is fully populated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb-resource ('Adjust pricing or rules for an existing listing') and enumerates the exact fields it touches (base price, floor/ceiling limits, dynamic pricing, pricing rules). It clearly separates this from the ~80 siblings that deal with creating, deleting, or shipping listings. Even the title 'Change Listing Price' is rendered specific by the field enumeration.
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 gives strong 'when-it-applies' context — it explicitly covers paused and out-of-stock listings, not just live ones, and explains when the verification gate trips on a price cut. However, it never explicitly differentiates from firestarter_update_listing (the nearest sibling), nor states when one should prefer the other. The follow-up action (firestarter_verify) is named, which is good, but selection guidance versus alternatives is absent, leaving the agent to infer which tool handles general listing edits.
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 that the tool performs a product search and diff immediately, which is an action beyond the readOnlyHint=false annotation. It does not mention potential side effects like cost, rate limiting, or whether the operation is synchronous, but it provides reasonable detail about the behavior. No contradiction with annotations is present.
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 ('Trigger an immediate check on a monitor'), followed by a clarifying sentence about what the check entails. There is no redundant information; each 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 tool with a single parameter and no output schema, the description provides sufficient context: it states what the tool does, when to use it, and the expected behavior. It does not explain return values, but that is not required given the absence of an output schema. The description is complete enough for correct usage.
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 for the single parameter 'monitor_id' with a clear description ('The monitor ID to check now'). The tool description adds nothing beyond the schema, but since the schema is already explicit, the baseline score of 3 is appropriate. No additional parameter nuance 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 states a specific verb ('Trigger') and resource ('check on a monitor'), and clearly distinguishes it from scheduled checks by saying 'immediate' and 'instead of waiting for the next scheduled check'. It also specifies the action ('Runs the product search and diff'), making the purpose unambiguous and distinct from sibling tools like watch or unwatch.
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 indicates when to use this tool: when an immediate check is needed, as opposed to waiting for the scheduled check. It contrasts with the alternative (waiting) and implies it is for on-demand execution. However, it does not explicitly mention when not to use it or reference other tools, but the usage 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 indicate idempotentHint=true, destructiveHint=true, and readOnlyHint=false. The description adds behavioral context about marking delivery and expediting escrow release, which goes beyond the annotations. 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?
Two concise sentences with no waste. The primary action and effect are front-loaded, followed by usage triggers. 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 single-parameter tool with no output schema, the description covers purpose, behavioral effect, and usage context. It lacks only explicit mention of side effects or prerequisites, but these are minor 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?
Schema coverage is 100% (execution_id has a clear description). The tool description adds no additional parameter-level information beyond what the schema already provides, so 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 verb 'Confirm', the target ('shipped or delivered order'), and the effect ('marks a shipped order delivered and expedites escrow release'). It distinguishes from sibling tools by explaining the unique benefit (expediting escrow release instead of waiting for carrier confirmation).
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 when-to-use triggers ('buyer says I got it, package arrived, or confirm delivery') and explains the advantage over the alternative (waiting for auto-release). It doesn't state when not to use it, but the guidance 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 provide idempotentHint=true and destructiveHint=true, and the description adds meaningful process context: it returns a browser link, payout enables only after the owner finishes onboarding, and calling it when already set up just reports that. It doesn't specify what destructive effect occurs, but the annotation already flags it.
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 front-loaded with purpose, then usage guidance, then parameter note. The parenthetical about earnings accruing from any country is useful context but slightly extends length; overall, every sentence 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?
For a tool with a single optional parameter and no output schema, this description covers purpose, when to use, return value (onboarding link), post-conditions (payouts enable), idempotent behavior, and parameter usage. No critical gaps remain for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with country fully documented as an ISO-3166-1 alpha-2 code and 'Only needed if onboarding asks.' The description only repeats this optionality, adding no new semantic detail, so the baseline score 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: 'Connect a Stripe payout account so a community-market owner can WITHDRAW their accrued earnings.' It also distinguishes from sibling tools by explaining it returns a Stripe onboarding link and enables payouts, rather than just listing/checking payouts or withdrawing directly.
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 gives explicit triggers: 'Use when an owner asks to get paid, cash out, set up payouts, or connect Stripe.' The sentence 'If already fully set up, it just says so' covers the already-done case, but no alternative tools or when-not-to-use conditions 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 indicate mutation (readOnlyHint false) and non-destructive (destructiveHint false). The description adds valuable behavioral context: the code is shareable, redeeming it attributes users to the program, and it enables earning. It doesn't contradict annotations and goes beyond them by explaining the attribution mechanism, though it omits details like code expiration or revocability, which is acceptable for the tool's apparent simplicity.
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: the first states the primary action and prerequisite, the second explains the community impact and optional tagging. Every phrase earns its place with no redundancy or fluff, and the key purpose 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 tool with three well-documented parameters and no output schema, the description covers the essential context: what it does, when to use it, and the intended audience (community members). It explains the attribution benefit and optional tagging. It doesn't explicitly mention the return value (the generated code), but that is implied by 'mint a shareable join code,' so the definition is adequately 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?
The input schema provides full descriptions for all three parameters (program_id, channel, campaign). The description only briefly mentions channel/campaign as 'tags for tracking,' which adds no new meaning beyond the schema. Since schema coverage is 100%, no additional compensation is needed, so a 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 action ('Mint a shareable join code') with a clear resource ('for a market you own') and connects it to sibling tools (firestarter_create_market and firestarter_join_market). It distinguishes this tool from others by focusing on the linking/attribution feature, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: the code is for markets you own and is redeemed by others, with optional channel/campaign tags. It references the prerequisite (firestarter_create_market) and the redemption flow (firestarter_join_market), but it doesn't explicitly state when not to use this tool or name an alternative for a different scenario. Still, the guidance is strong enough to steer correct 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 indicate this is a non-readonly, non-idempotent write, and the description supplements that with useful behavior: the purchase history is consolidated so the item can be reordered later, and live keys are refused with TEST_MODE_ONLY. It doesn't cover duplicate handling or outputs, but adds meaningful 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?
Three sentences, each earning its place: what the tool does, when to call it, and the environment limitation. The core purpose is front-loaded and no filler is present.
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 an 11-parameter write action with no output schema, the description gives enough guidance about invocation timing, accepted data breadth, and the test-mode restriction. It lacks explicit notes on response/error handling, but the schema and the 'whatever details' guidance mitigate that gap.
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 every parameter already has a description. The tool description adds some contextual guidance about 'whatever details are visible on the confirmation page' but doesn't explain individual parameters beyond what the schema provides. 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: recording a purchase completed outside the network, with concrete examples (Lazada, Shopify) and the purpose of keeping unified purchase history and enabling reorders. It clearly distinguishes itself as the off-network recording tool from siblings that handle listings, imports, or delivery.
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 when to call it — right after an off-network checkout succeeds — and gives context about using whatever confirmation-page details are available. It also states the live-key restriction, acting as a when-not-to-use condition. It doesn't name alternative sibling tools, but the guidance is clear enough for correct 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 indicate this is a write operation (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds useful context: the requirement that the order must be delivered/completed, and the one-review-per-order restriction, 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?
The description is three short sentences, front-loaded with the core purpose, and every sentence adds value. 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 tool with three parameters and no output schema, the description covers the use case, preconditions, and a key constraint. It doesn't mention error conditions, but that's acceptable given the simplicity and the clarity of the 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 coverage is 100%, so all parameters are fully documented. The description mentions the rating scale and optional comment, but these details are already present in the schema. It does not introduce any new meaning 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 clearly states the action (submit a review) and the specific resource (a delivered/completed order). It also specifies the rating scale and the fact that it's for buyers, distinguishing it from sibling tools like firestarter_confirm_delivery or firestarter_track_order.
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 when the buyer wants to rate their purchase experience" and adds a key constraint: "Only one review per order is allowed." It doesn't explicitly mention alternatives, but the condition is clear enough for an agent to decide when to invoke this tool versus other order-related actions.
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 destructiveHint=false, and the description adds valuable behavioral details: values are masked (partial street, no zip/phone), the default address is marked, and addresses are referenced by id so full values are not needed. This contextualizes the read-only nature 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action ('List the buyer's saved shipping addresses'), then adds supporting details about masking, defaults, and integration. While it is a bit longer than strictly necessary, each sentence contributes meaningful information, and the structure is logical.
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?
Without an output schema, the description is responsible for explaining return values. It covers the key aspects: masked addresses, default address marking, and the address_id field's role in downstream tools. It does not mention pagination or error scenarios, but for a simple list operation this is likely sufficient. The tool is simple enough that the description provides adequate context for an agent.
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 needed. The schema description coverage is 100% (trivially), and the description appropriately focuses on the output and integration rather than inputs, which is consistent with a no-arg listing 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 the verb 'List', the resource 'saved shipping addresses', and the masking attribute. It also explains the primary purpose of returning address_id for use in firestarter_execute and firestarter_approve, and implicitly distinguishes itself from sibling tools like firestarter_save_address and firestarter_shipping_options.
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: to list saved addresses and obtain IDs for use in other workflows. The statement that 'a saved address never has to be re-typed' communicates a practical benefit. It does not explicitly state when not to use it, but the purpose is clear enough that an agent can infer its role relative to related 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 indicate destructive=true and idempotent=false. The description adds meaningful behavioral detail: it may charge the drop wallet or seller proceeds, may create a pending request needing seller approval, and can be tier-gated for early access. 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is verbose and contains redundant phrasing: 'first-come first-served, one per member' appears both in the first and second sentences, and the funding/approval explanation is wrapped in a very long, multi-clause sentence. While informative, it could be tightened without losing 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?
Given the tool's complexity (7 params, funding decisions, approval flows) and lack of output schema, the description covers the main operational outcomes well. It explains what happens in different scenarios, but does not mention what the API returns (e.g., drop ID or status), which would be useful for follow-up calls.
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?
Schema coverage is 100% and each parameter already has a description. The tool description adds cross-parameter semantics (e.g., max_claims × discount = pot, priority_hours + min_tier = tier-gated window, expires_in_hours default) and explains how funding relates to the listing owner, giving a fuller mental model 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?
States a specific verb ('Create') and resource ('community-sponsored DROP on a market you own') and clearly differentiates from the sibling tool firestarter_set_market_tiers, which 'never discounts.' This distinguishes it from similar market-related tools without needing to open schemas.
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 usage context: it explains when a drop goes live immediately vs. waits for approval, and how funding works depending on the listing owner. It explicitly contrasts with firestarter_set_market_tiers, giving an alternative, though it does not state a crisp 'use this when...' directive for all 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 usefully discloses that claim is a first-come, first-served reservation, enforces one per member, and applies the discount to the buyer's purchase. It also notes that test/live behavior follows the API key's environment, adding important behavioral context beyond the bare annotations.
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 front-loaded with the core concept and then covers each action in order. It is moderately detailed with no unnecessary fluff; every sentence contributes context for call behavior, though it is slightly longer than strictly necessary.
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 what is returned by 'list' (discount, slots remaining, tier-gated status) and the effect of 'claim'. Given there is no output schema, this is reasonably complete, though it does not describe the response shape for 'claim' or cover explicit failure reasons such as sold-out or early-access gating.
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, but the description adds meaningful semantics by tying listing_id to listing live drops and drop_id to reserving a slot. It also enriches the action enum by describing what each action does without contradicting 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 names a specific verb and resource: it lists live drops and claims drop slots. It clearly explains the community-sponsored drop concept and distinguishes the two action modes. The tool's purpose is clearly differentiated from community update/approval sibling tools like create_drop, approve_drop, and market_drops.
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 instructions: use action 'list' with a listing_id to see live drops, and action 'claim' with a drop_id to reserve a slot. This is clear and actionable, though it does not explicitly name alternatives or say when not to use this tool.
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 cover the read-only, non-destructive profile (readOnlyHint=true, destructiveHint=false), and the description adds genuinely non-obvious behavior beyond them: omitting listing_id returns drafts that still need activation, and share links exist only for active live listings, not sandbox or draft ones. This is exactly the kind of nuance an agent needs to answer seller questions about why a listing lacks a share link.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, each earning its place: core purpose plus returned fields, parameter-dependent behavior, usage trigger, and the share-link availability rule. The most decision-relevant information (viewing seller-side listings) is front-loaded, with zero 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 read-only tool with one optional, fully documented parameter and an output schema present, nothing material is missing. The description covers both invocation modes, the draft/sandbox edge cases, and the usage trigger, while annotations and the output schema cover the safety profile and return shape.
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 the schema already explains the listing_id prefix (lst_...), the full-detail behavior, and the omit-to-list-all behavior. The tool description reinforces the same points, adding only the 'drafts that still need to be activated' nuance. With the schema doing the heavy lifting, the baseline 3 applies.
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 opens with a specific verb and scope — 'View your own product listings (seller side)' — and enumerates the returned fields (name, current price, inventory, status, demand, live share link). This clearly frames it as a seller-side read operation distinct from create/update/delist siblings, but it never explicitly names a sibling, so differentiation from firestarter_list or firestarter_product remains implicit rather than stated.
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?
'Use this when a seller wants to see, verify, or share what they have listed' supplies an explicit trigger condition, and the pass-listing_id versus omit guidance covers both invocation modes clearly. However, no when-not conditions or named alternatives are given, so the agent must infer the boundary against siblings like firestarter_demand and firestarter_product.
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=false and destructiveHint=false, so the description isn't the sole source. It adds idempotency (returns existing profile without error) and the cross-tool dependency. It doesn't detail response shape or side effects beyond idempotency, but given annotations coverage, this is a solid 4.
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?
Description is longer than minimal but every sentence earns its place—precondition, idempotency, expected error, immediate usability. Front-loaded with the core purpose. Slight verbosity but justified by the context needed.
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 and no output schema, the description covers prerequisites, behavior, and relationships. It hints at return profile in the idempotent case but doesn't explicitly state what a successful first-time registration returns. Minor gap, but overall well-rounded.
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 descriptions cover 100% of parameters and are already rich (e.g., country's Stripe implication, type defaults). The description adds 'Only requires a business_name' which is redundant with the required field. No new semantic value beyond the schema; 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?
Clear verb 'register', resource 'account as a seller', and explicitly names dependent tools (list, import, connect_shopify). The description states what the tool does and differentiates it from siblings by explaining it's the precondition for listing/importing. Highly specific.
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 states when to use (before listing/importing/connecting) and the symptom (NO_SELLER_PROFILE error) if not yet registered. Also clarifies that payouts can be deferred, so it's not needed for immediate listing. Clear guidance on when and when not to use.
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 signal destructiveHint=true and idempotentHint=false. The description adds meaningful behavioral context by explaining the financial consequences (voiding a hold vs. refunding a capture) and the shipped-order limitation, going beyond what the annotations alone convey.
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 with no filler. It front-loads the core action and then provides the key exception and alternative, making it easy for an agent to parse quickly.
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 operation is simple with only two parameters and no nested objects, and the description covers the important state-dependent outcomes. No output schema exists, and while a note about the expected response would make it fully complete, an agent can still invoke this tool correctly based on the provided guidance.
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 execution_id and reason are already fully documented in the input schema. The description does not add parameter-level detail, which is acceptable given the schema's completeness but 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?
The description clearly states the action ('Cancel'), the target ('an active execution'), and the precise scope: voiding an uncaptured authorization hold or refunding a captured payment. It also distinguishes itself from firestarter_return, which is appropriate for shipped orders.
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 names firestarter_return as the alternative when an order has shipped, creating a clear decision boundary. It also describes the two payment states where cancellation applies, giving the agent the context needed to choose this tool versus a 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 destructiveHint=true and readOnlyHint=false, so the mutation nature is known. The description adds valuable behavioral context beyond annotations: the cancellation is permanent (stops being visible, can never be approved), and it is state-dependent (only pending requests). However, it doesn't disclose any additional side effects like whether it triggers notifications or affects related records, but given annotations cover destructive intent and idempotentHint=true, a 4 is appropriate — the description adds meaningful state-specific behavior that annotations don't.
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 all essential information: what the tool does, preconditions, permanence, and the fallback action. Front-loaded with the primary action and scoped immediately. 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?
For a destructive, state-dependent mutation with two simple string parameters, the description covers: the precondition (pending, own market), the effect (invisible to seller, never approvable), the fallback (re-create), and the invalidity states. With annotations covering the destructive/idempotent profile and full schema coverage, this is nearly complete. A minor gap: it doesn't state what the response looks like, but since there's no output schema and the state outcome is clear, a 4 is fair rather than 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters (program_id and drop_id) are documented with descriptions and source references. The tool description aligns with the schema by explaining the drop_id comes from create_drop or market_drops, and program_id from my_markets. Since the schema already carries the semantic weight, the description doesn't need to add much. Baseline 3 is correct.
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 (withdraw a drop request you created) and the specific context (pending seller approval on a market you own). It defines who can use it, what it acts on, and the exact state required. It distinguishes itself from siblings like firestarter_approve_drop and firestarter_reject_drop by focusing on cancellation by the creator, not the seller. The verb+resource is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: only on still-pending requests you created on a market you own. Explicitly states when not to use: if already live, expired, exhausted, or already decided, it can't be cancelled. It even references the alternative action (create a new request with firestarter_create_drop) if the agent changes its mind. This is exemplary usage 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=true, and the description consistently reinforces the read-only behavior. It goes beyond annotations by specifying the exact returned values (current margin, platform ceiling, margin earned so far) and clarifies the economic meaning relative to share_bps, which helps an agent understand the tool's behavioral scope without an 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 longer than minimal, but every sentence contributes: definition, return values, read-only guidance with the setter alternative, and a crucial distinction from a similarly named concept. It is front-loaded with the core purpose and the disambiguation earns its length, though it could be tightened slightly.
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 tool with no output schema, the description is complete: it explains what the developer margin is, what values are returned, that the tool is read-only, which tool performs writes, and how it differs from a related but distinct concept. An agent has enough context to select and call this 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%, and the sole parameter margin_percent is already documented in the schema as "IGNORED here — this tool only reads." The tool description reinforces the read-only nature and points to the setter tool, but it does not add substantial new parameter-level meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: "Read this organization's DEVELOPER MARGIN." It clearly defines what the margin is, what is returned (current margin, platform ceiling, margin earned so far), and explicitly differentiates itself from the setter tool and firestarter_create_market's share_bps, making it unmistakable among the many siblings.
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 usage direction: it is a read operation, and to set or change the margin the agent should use firestarter_set_developer_margin. It also explicitly warns against confusing this with firestarter_create_market's share_bps, giving both the alternative and the condition that distinguishes them.
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 read-only, open-world, and non-destructive behavior. The description reinforces this and adds 'no sign-in needed', which is not in annotations, providing extra clarity about no authentication requirement.
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 main purpose, followed by usage guidance and alternatives. It avoids unnecessary fluff and maintains a clear structure.
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 description is complete for a read-only list tool: it specifies what it returns, when to use it, how it differs from related tools, and its side-effect-free nature. No output schema exists, so no return-value explanation 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 has full coverage with a descriptive parameter 'limit' (max communities, default, max). The tool description does not mention the parameter, but since schema coverage is high, the baseline of 3 is appropriate; no additional meaning 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 clearly states the tool's purpose: browsing public community markets a buyer can join, and enumerates the returned fields. It also distinguishes from sibling tools by explicitly naming firestarter_market_preview and firestarter_join_market for alternative 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 states when to use the tool ('Use when a buyer asks what communities exist...') and provides clear alternatives for related actions, making the usage conditions 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?
The description goes well beyond the annotations by explaining the Stripe Checkout flow, the fact that the wallet credits only after payment completes, the $1.00 minimum, and the notable side effect that drops go live immediately once funded. This gives the agent a strong mental model of the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than strictly necessary, but every sentence adds value: purpose, mechanism, side effects, return value, and usage trigger. It is front-loaded with the core action and then provides supporting detail.
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 tool with no output schema, the description is complete. It explains what the tool returns, what happens after payment, how the wallet relates to drops, and when to invoke it. Nothing essential is missing.
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 schema already describes amount_cents with its minimum. The description repeats the $1.00 minimum but adds no new parameter-level meaning beyond what the schema provides, 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 opens with a specific verb and resource: 'Deposit money into your drop wallet via Stripe Checkout.' It clearly distinguishes this from related wallet tools like firestarter_wallet_balance and firestarter_withdraw_wallet, and even ties it to firestarter_create_drop.
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 it: 'Use when an owner asks to fund/top up/add money to their drop wallet.' It does not explicitly name alternatives or when-not-to-use conditions, but the stated trigger is clear enough for an agent to route correctly.
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?
Read-only behavior is already captured by annotations, but the description adds valuable specifics: 'nothing is bought and no approval is created', options are 'live', and results distinguish buyable vs browse-only products. This goes beyond the annotation's simple readOnlyHint and gives the agent a clearer behavioral model. 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?
The description is three sentences and every sentence earns its place: purpose and non-destructive guarantee, return-value highlights, and the usage framing with firestarter_execute. It is front-loaded with the most important fact (no purchase starts) and contains 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 10 parameters, a nested context object, and an output schema, the description covers purpose, safety, eligibility semantics, and the relationship to firestarter_execute. Pagination and currency-display behavior are already documented in the parameter schema, so the description does not need to repeat them. Minor missing piece: it could more explicitly mention paging through large result sets, but the schema handles that.
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 100%, so the baseline is 3, but the description adds meaning by linking the eligibility outputs to the relevant parameters: 'in budget, can arrive by the deadline, and ships to the destination' maps to max_price, deadline, and city/country. This helps the agent understand how those parameters influence the returned options beyond their individual field descriptions.
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, resource, and scoping constraint: 'Preview real products for a natural-language request WITHOUT starting a purchase.' It explicitly names the purchase counterpart, firestarter_execute, and clarifies that this tool is the read-only pre-purchase view, so an agent can distinguish it from siblings without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: use this to answer 'what can you get me?' and as the step 'before any purchase starts (firestarter_execute)'. It names the closest alternative, firestarter_execute, and implies this tool should be called before committing. It does not explicitly address broader catalog-search alternatives, but the guidance 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 readOnlyHint and destructiveHint annotations already mark it safe; the description adds test-environment-only limitation and live-key refusal behavior beyond the schema. It also clarifies that the refusal says nothing about Firestarter order history, which is useful contextual 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?
Three dense sentences front-load the core scope ('OFF-NETWORK purchases only') and each subsequent sentence adds a necessary distinction or caveat. There is 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 read-only list/get tool with fully described optional parameters, the description covers scope, exclusions, and environment behavior. It does not spell out the result shape, but this is not a blocker given the schema and 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?
All four parameters have schema descriptions, so the schema carries the semantic load. The description does not add per-parameter meaning beyond what is already present.
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 the pilot log of off-network purchases and explicitly distinguishes it from Firestarter order history, which lives in firestarter_status. This makes the tool's scope unambiguous relative to its siblings.
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 states the exact condition for use: off-network purchases recorded with firestarter_record_purchase, and explicitly says it is NOT for 'my orders' / 'order history', directing agents to firestarter_status. It also warns that live keys get a TEST_MODE_ONLY refusal, preventing misrouting.
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 indicate readOnlyHint=false, destructiveHint=false, and openWorldHint=false, which already signal this is a mutating but non-destructive operation. The description adds valuable behavioral context: it explains the default label behavior when omitted, the is_default flag's effect on future orders, and that it returns the saved address id. It also clarifies the country inference behavior in the schema, which is a behavioral trait. 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?
The description is concise and well-structured. It front-loads the core purpose, then provides usage context, parameter guidance, and return value in a logical flow. Every sentence adds value without redundancy. The length is appropriate for a tool with 10 parameters.
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 (10 parameters, 2 required), the description covers the essential usage context, return value, and key parameter behaviors. The schema covers all parameter details. The description could be more complete by mentioning potential error cases or prerequisites (e.g., whether the buyer must exist), but these are minor gaps. The output schema is absent, but the description states the return value (saved address id), which is sufficient.
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 100%, so the schema already documents all 10 parameters. The description adds value by explaining the label default behavior and the is_default flag's effect, which are not fully captured in the schema. It also reinforces the country inference behavior. However, it doesn't add much beyond what the schema already provides for most parameters, so a 4 is appropriate rather than 5.
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 ('Save'), the resource ('a delivery address to the buyer's address book'), and the purpose ('for reuse on future orders'). It distinguishes itself from siblings like firestarter_save_ship_from (which saves a ship-from location) and firestarter_addresses (which likely lists addresses). The context of when to use it (after a purchase or explicit request) further clarifies its 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?
The description provides clear usage context: 'Use this after a purchase when the buyer gave a new address, or when they explicitly ask to save an address.' It also explains the optional label and is_default parameters. However, it doesn't explicitly mention when NOT to use it or name alternative tools (e.g., firestarter_addresses for viewing addresses), which would strengthen the 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=true and destructiveHint=false, covering the safety profile. The description adds value beyond annotations by disclosing the aggregated/analytics nature of the data (not raw records) and hinting at a time-series structure via the '30-day daily breakdown.' 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 tight sentences with zero waste. The first sentence front-loads the purpose and metrics, the second provides the usage trigger. 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 zero-parameter, read-only analytics tool, the description is complete: it states what data it returns (metrics list) and when to invoke it. Because there is no output schema, the description could specify the exact return format/field names, which is a minor gap, but for this tool's simplicity it is largely sufficient.
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 nothing to explain. Per rubric, 0 params earns a baseline of 4. Schema coverage is trivially 100% and the description correctly introduces no parameter guidance since none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('view'), a resource ('seller revenue and order analytics'), and lists the concrete metrics delivered (total revenue, order count, AOV, 30-day breakdown). The scope is clear and it distinguishes itself from siblings like firestarter_seller_orders (order-level detail) and firestarter_market_earnings (market-level).
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 explicit context: 'Use when a seller asks about their performance, earnings, or sales trends.' This clearly signals the triggering scenario. However, it does not name sibling alternatives or state when NOT to use it (e.g., versus firestarter_seller_orders for raw order detail), so it stops at clear context without 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 declare idempotentHint=true, destructiveHint=true, readOnlyHint=false, and the description aligns with these: it is a state-changing write (supports destructiveHint), and setting the same limit again would be idempotent (supports idempotentHint). The description adds critical safety context beyond annotations: orders at the limit are paid without confirmation, the stored value is exact/precise, and the success signal is the response echo of the stored setting. It does not spell out every effect (e.g., whether disabling is reversible immediately), but it discloses the most important safety-critical behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The prose is dense but organized: identity/scope first, operational semantics second, parameter guidance third, safety caveat before the read-sibling pointer. It is longer than strictly required, but nearly every sentence contributes functional information. The trailing sentence about the read sibling is brief and relevant. No clutter 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?
The description is complete for a mutation tool with no output schema. It explains the safety profile (orders auto-approve, exact value is safety-critical), the persistence scope (account-level, across surfaces), the two modes, the maximum limit, and the recommended read route. An agent can decide correctly whether to call this tool and what to pass without requesting additional info.
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 even with no additional parameter details. The description nevertheless adds useful framing—context that orders at or below the limit pay without manual confirmation, and the safety-critical precision of the stored value—supported by examples like 50 and 0. It does not add brand-new param syntax beyond the schema, but it does explain the semantics well; 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 ('Set or disable') and a precise resource: the buyer's persistent, account-level auto-approval limit. It clearly distinguishes itself from the sibling firestarter_auto_approve_limit, noting that this tool sets while the sibling reads. The scope ('account-level', 'across all surfaces') removes ambiguity, and the maximum-limit and 0-value semantics are 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?
The description explicitly states when to use the tool ('Set or disable the auto-approval limit'), how to choose between the two mutually exclusive parameters (set_limit_usd OR disable=true), and the read alternative: 'Use firestarter_auto_approve_limit to read the current value without changing it.' This covers the key decision an agent faces—whether to modify or only query—and leaves no room for guessing.
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, the description discloses important consequences: approval makes the drop live immediately, the discount comes from the seller's proceeds rather than the platform fee, and the requesting community is notified. This reveals the financial and side-effect impact of the action, which the annotations do not cover.
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: it states the action and resource first, then adds the important margin impact and notification behavior. Every sentence earns its place without 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 single-parameter approval tool with no output schema, the description is complete: it identifies the source of the drop_id, explains what happens on approval, flags a financial consequence, and covers user notification. An agent has enough context to decide and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole drop_id parameter already has 100% schema coverage with a direct description. The description reinforces that the ID comes from firestarter_drop_requests, but it adds little meaning beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('Approve a pending community drop request') and a specific resource ('on one of your listings'), and it ties the request back to firestarter_drop_requests, which distinguishes it from generic siblings like firestarter_approve. It also contrasts effectively with reject/cancel paths by focusing on the approval-to-live transition.
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 for when to use it: when there is a pending community drop request from firestarter_drop_requests that should go live. It does not explicitly enumerate alternatives like firestarter_reject_drop or firestarter_cancel_drop, but the source link and 'pending' condition make the intended usage unambiguous.
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 provide minimal signal (readOnlyHint: false, destructiveHint: false), leaving the description to carry the burden — and it delivers. It discloses the non-destructive nature ('books nothing, charges nothing'), surfaces a real-world quirk (Lalamove in Thailand requiring coordinates), describes the return ordering ('cheapest-first'), and warns about the downstream consequence (quoting is not booking; booking is a real charge requiring human confirmation). 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Dense but every sentence earns its place — purpose, when-to-use, safety, parameter guidance, and downstream warning. It is front-loaded with the core purpose. The one structural demerit is that it's a wall of six sentences in a single paragraph; breaking the safety and Lalamove notes into separate lines would improve scannability, but there is no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a high-complexity tool (11 params, no output schema), the description covers the essentials: when to fire, safety profile, location-pin handling, return format (cheapest-first, quote_ref), and the critical warning that booking is a real charge requiring user confirmation. It could add error-case behavior or how quotes can fail (e.g., no couriers in area), but nothing an agent needs to invoke it correctly is obviously 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?
With schema coverage at 55%, the description meaningfully compensates for the undocumented lat/lng parameters: 'Include lat/lng for both stops when the user shared a location pin — some couriers cannot quote without coordinates.' It also maps the domain ('courier crew,' 'bulky') to the bulky/two_person params. It doesn't explicitly address needs_disassembly or declared_value_cents, but the parameter guidance it adds goes well 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?
States a specific verb+resource ('Get pickup+delivery quotes') with a clear scope ('for a PHYSICAL item... weight racks, sofas, appliances'). It achieves differentiation from siblings like firestarter_shipping_estimate and firestarter_assist_book by describing exactly what this tool does and what it hands off (quote_ref → assist_book).
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 explicit when-to-use triggers: 'Use when a buyer or seller asks how to move an item, or proactively when an item is clearly bulky.' The 'Pure price check: books nothing, charges nothing' implicitly distinguishes it from the booking sibling firestarter_assist_book, and the warning that booking 'requires the human's prior confirmation' sets a condition for the follow-up action. It could name an alternative tool to rule out (e.g., shipping_estimate), 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 indicate readOnlyHint=false and destructiveHint=false, but provide little else. The description adds meaningful behavioral context: that confirming notifies the buyer, and that it is the gate before shipping. It also warns about the order_id field misuse (not the exec_... execution id). A small shortfall is not describing the response or side effects (e.g., irreversible nature), accounting for the not-perfect score.
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 purpose, though it packs many details into two sentences. The sentences are information-dense but readable and without redundancy, earning a high score slightly below perfect because the long first sentence could be split for readability.
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 complexity (single parameter, clear flow context), the description is nearly complete. It covers when to use, prerequisites, and the parameter gotcha. The only omission is what the success response looks like or potential failure states, but given the tool's simplicity and schema coverage, this is minor.
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 100%, and the single parameter (order_id) is clearly explained in the description with a specific caveat ('the seller_earnings id, not the exec_... execution id'). The description adds clarity beyond the schema by emphasizing the correct field source, which earns an above-baseline score.
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 specific action (accepting a pending incoming order), identifies it as step 2 of a fulfillment flow, and names the relevant sibling tools. This distinguishes it from firestarter_ship_order and firestarter_seller_orders explicitly.
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 when-to-use guidance, names the prerequisite tool (firestarter_seller_orders), the following tool (firestarter_ship_order), and explicitly notes exclusions ('Only orders still in pending can be confirmed') and 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?
Annotations are limited (readOnlyHint=false, openWorldHint=true, destructiveHint=false), so the description carries the burden and does so well. It explains the two invocation modes (no args for status, with shop_handle for link creation), what the responses contain, and that the catalog syncs automatically. It doesn't explicitly warn about side effects like 'a connection is initiated', but it implies a non-read-only action, and nothing contradicts annotations.
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 long but every sentence earns its place: it opens with the purpose and flow, then explains the two calling conventions, gives usage triggers, explains the handle format, and names the alternative. It's well-structured, front-loaded, and avoids 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?
With no output schema, the description appropriately describes return outcomes (connection status/store name/last sync time vs. missing-handle report). It covers the tool's place in the flow, the optional parameter, and how to obtain it. Given the complexity (dual modes, integration with Shopify), this is complete 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?
Schema coverage is 100% (shop_handle is fully described), so baseline is 3. The description adds value by explaining the dual behavior: omitting the parameter checks status, while providing it triggers the link minting. It also elaborates on how the seller can find the handle, which goes beyond the schema. This justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action (connect a Shopify store) with a clear resource (Firestarter) and positions it as step 1 of a defined flow, naming the subsequent siblings (firestarter_listings, firestarter_sync_shopify, etc). It distinguishes itself from firestarter_sync_shopify by function, so an agent can easily tell them apart.
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 this whenever a seller mentions Shopify, wants to connect/link their store, or asks why their products aren't showing up' and directs to firestarter_sync_shopify for refreshing an already-connected store. This gives clear when-to-use and when-not-to-use guidance with an alternative named.
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 destructiveHint=true and readOnlyHint=false, and the description adds meaningful behavioral context: deleting the primary location causes quotes to be rated from the platform origin until another location is added or promoted, and only seller accounts can do this. 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 a tight two-sentence definition with the core action front-loaded. Every clause carries relevant information: the object, the id format, the consequence, and the authorization scope.
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 one-parameter destructive tool, the description plus annotations cover what is deleted, the side effect on quoting, the auth restriction, and the related save tool. No output schema exists, and the missing details are minor for an agent selecting 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?
The schema covers 100% of parameters with a clear description of location_id including the floc_... pattern. The tool description repeats that pattern and adds the source table name, but does not meaningfully deepen the semantic understanding 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 names a specific verb ('Delete') and resource ('seller ship-from (fulfillment) location'), and pins down the identifier pattern ('floc_...') plus the source table ('firestarter_ship_from_locations'). This clearly separates it from the listing tool and the save/update tool in the sibling 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?
It states the operative context ('Seller accounts only') and describes the consequence of deleting the primary location, explicitly pointing to firestarter_save_ship_from as the path to add or promote a replacement. It does not spell out exhaustive when-not-to-use cases, but the guidance is sufficient for this tool.
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 beyond annotations by disclosing that joining REPLACES any previously supported community and moves attribution for all future orders. It also clarifies that sales attribution applies only when enabled, adding meaningful nuance beyond destructiveHint and idempotentHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four front-loaded sentences, each earning its place: what the action does, the key destructive effect, when to use it, and the relevant alternative. No filler or redundant restatement of the tool name.
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 one-parameter tool with an output schema and annotations, the description is complete: it explains the trigger, the effect on prior support, the attribution behavior, and the preview alternative. Nothing critical is missing 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 coverage is 100% and the code parameter already has a clear description. The tool description adds the alias 'Firestarter join/market code' and reinforces that the code comes from the community, but it does not significantly extend 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?
States a specific verb ('Join') and resource ('community market using its share code'), and explains the attribution effect. It also names the sibling firestarter_market_preview, distinguishing joining from previewing before commitment.
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 tells the agent when to invoke: when a user pastes a Firestarter join/market code or asks to join a community market. It does not enumerate exclusions, but the trigger is concrete and the preview sibling is offered as the pre-join alternative.
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, the description discloses concrete consequences: 'It never goes live, nothing is charged against your proceeds, and the requesting community owner is notified.' It also clarifies that the decision is one-off and that the community can ask again unless standing trust is revoked, which is valuable behavioral context not present in the schema or 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 with no filler: the action is front-loaded, followed by side effects, then scope and the relevant alternative. Every sentence 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?
For a simple two-parameter rejection action, the description covers what happens, what does not happen, who is notified, and the boundary of the decision. No output schema exists, but the outcome is described well enough 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%, so the schema already documents both drop_id and reason. The description repeats that drop_id comes from firestarter_drop_requests and that reason is optional and shown to the owner, but it adds no new parameter-level meaning 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 opens with a specific verb and resource: 'Decline a pending community drop request on one of your listings.' It also names the source collection (firestarter_drop_requests) and distinguishes the action from the standing-trust alternative, so an agent can tell it apart from siblings like firestarter_approve_drop and firestarter_untrust_community_drops.
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 scopes the action to a single request and explicitly points to firestarter_untrust_community_drops for revoking standing trust, giving the agent a when-not-to-use signal. It does not explicitly mention the accept alternative (firestarter_approve_drop), but the context makes the decision boundary 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 indicate a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds meaningful context: sanctioned/embargoed destinations remain blocked, the policy applies to one listing (scope), and mode 'domestic' is the default. This exceeds the structured fields 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, front-loaded with purpose and use context, and every sentence adds information. It covers modes, examples, a safety note (sanctions), and scope in a few lines 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 tool with 4 parameters, 3 modes, and no output schema, the description is thorough: it explains each mode, parameter constraints, default behavior, exclusions, and a critical edge case (sanctioned destinations). An agent has enough to call it correctly without additional lookup.
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 baseline is 3. The description adds value by stating that 'domestic' is the default, clarifying that 'list' auto-includes the ship-from country, and giving concrete examples for countries and exclude. This enriches beyond the schema's own descriptions without redundancy.
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: 'Set where a seller is willing to ship a listing.' It uses a specific verb (set) and resource (shipping policy), and mentions concrete use cases like a checkout failure. It is distinct from sibling shipping tools (options, estimate) because it focuses on policy mutation.
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 scenarios: when a buyer requests a destination not covered, and for general changes to shipping reach. It explains each mode with examples. It does not explicitly say when NOT to use it or name alternative tools, but the context is strong 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?
Annotations already declare readOnlyHint true and destructiveHint false, and the description reinforces this by stating 'Read-only' and 'this tool only reads.' It adds context by naming the two specific values returned (spend cap and alert threshold) and clarifying that the input parameters are ignored, 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 sentences with no wasted words. The main purpose is front-loaded, the read-only nature is stated early, and the pointer to the sibling tool is placed exactly where it is needed. Every sentence 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?
For a read-only, zero-required-parameter tool with no output schema, the description covers what the agent needs: what is read, the read-only guarantee, and the alternative for modifications. It even includes a practical scenario (SPEND_CAP_EXCEEDED) that helps the agent understand when to switch tools. No critical information is missing.
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 schema itself already explains that all three parameters are 'IGNORED here' and points to the set tool, so the description doesn't add additional parameter-level semantics. It does provide useful context about what the tool actually reads, but this is more about output than 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 opens with the specific verb 'Read' and identifies the exact resource: the buyer's monthly spend cap and the alert threshold. It also explicitly names the sibling tool it is not (firestarter_set_spend_cap), so an agent can distinguish read from write operations without inspecting the schema.
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 states when to use this tool (to read the cap/threshold) and explicitly directs the agent to firestarter_set_spend_cap for raising, lowering, setting, or removing the cap. It even provides a concrete trigger context (SPEND_CAP_EXCEEDED) where the alternative should be used, leaving no ambiguity about 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 destructiveHint=false; the description adds meaningful context by specifying it only works after an order has been paid and shipped. It also discloses what kind of tracking detail will be returned. This is good behavioral context without 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?
Three short, information-dense sentences. The core purpose is front-loaded, the output payload is listed succinctly, and the alternative routing to firestarter_status is in the final sentence. 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 single-parameter, low-complexity lookup tool, the description is complete. There is no output schema, so the description accurately summarizes the return contents. It also states the precondition and the alternative tool, leaving no obvious gap for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents execution_id with a clear description and format hint (exec_...), and schema description coverage is 100%. The tool description does not add significant parameter-level semantics, 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 uses a specific verb and resource: 'Track a shipped order's delivery status.' It also names what will be returned, and the closing sentence distinguishes it from firestarter_status. An agent can correctly identify this as the delivery-tracking tool among dozens of siblings.
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 trigger language is given: use when a buyer asks 'where's my order?' or 'when will it arrive?'. It also provides a clear exclusion condition: for unpaid/unshipped orders, use firestarter_status instead. This gives 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?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the write nature is expected. The description adds key behavioral details: ownership requirement, clearing semantics, and that only specified fields are changed. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient, leading with the core purpose and then specifics. It is slightly long but every sentence contributes (ownership, fields, clear behavior, alternatives). No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 params, full schema coverage, and annotations, the description covers ownership, field selection, clearing, and routing to siblings. The one minor gap is that it doesn't explicitly state that fields not passed remain unchanged (though 'pass at least one' implies it). Overall, complete enough 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?
Schema coverage is 100%, so each parameter is documented in the schema. The description adds semantic value beyond the schema by clarifying that empty strings clear fields and that at least one field must be provided, which enhances understanding of the 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 states a specific verb ('update'), resource ('community market you own'), and the exact fields (display_name, tagline, discoverable). It distinguishes from siblings by naming firestarter_set_market_handle and firestarter_set_market_picks as alternatives for handle and picks. No ambiguity.
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 pass at least one field, clarifies when to clear fields with empty strings, and identifies sibling tools for other use cases (handle and picks). This is direct, actionable guidance with no ambiguity.
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 destructiveHint=false, so no contradiction there. The description adds value by revealing the full status enum (active, scheduled, expired, exhausted, paused), the cost-tracking behavior, and the natural-language queries it serves.
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 with zero fluff: the core purpose, the key statuses, and the user-question examples all earn their place. The most important info is front-loaded, and the examples are illustrative without being verbose.
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, read-only list tool with strong annotations, the description is complete. It tells the agent what is returned (vouchers, status, cumulative cost) and gives rich usage context; no output schema or pagination details are needed at this complexity level.
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 schema coverage is trivially 100%. No parameter documentation is needed, and the description correctly avoids inventing any.
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 resource ('vouchers'), then clarifies with parentheticals (coupons/promo codes/discount codes) and enumerates the statuses returned. The example user questions ('what discounts am I running?', 'how is SUMMER20 doing?') make the tool's scope unmistakable, even distinguishing it from sibling create/update voucher 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 phrase 'Use this to answer...' plus two concrete example queries gives clear context for when to invoke this tool. It doesn't explicitly name alternatives or exclusion criteria, but the examples effectively signal 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?
Annotations already declare readOnlyHint=false and destructiveHint=true, lowering the burden. The description adds meaningful behavioral context beyond that: it explains what each action does ('withdraw' = drop the dispute, 'escalate' = ask Firestarter to review), which behaviors change state, and the operational pitfall that images must be passed as public URLs rather than base64 because a photo 'is far too large to survive being printed into a tool call.' It does not, however, fully describe response structure or side effects such as rating impacts, so it stops just short of 5.
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 dense paragraph, but every sentence earns its place: audience, triggers, invocation patterns, and the sibling alternative. The key scoping statement (buyer side) is front-loaded. It is long, but the length is justified by 11 parameters and 8 actions; only a modest amount of tightening could remove without losing signal.
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 complex tool with 11 parameters, 8 actions, and no output schema, the description covers the full decision space: when to call, what to pass for each use case, which parameter combinations are valid, and what the user is expected to see (list of disputes, status of one order, or full thread). An agent has everything needed to select, compose, 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 coverage is 100%, so the baseline is 3. The description genuinely adds beyond the schema by documenting the calling idioms: how the tool behaves with no arguments, how execution_id can look up a dispute, and how execution_id can stand in for dispute_id on action parameters. The 'never rebuild it as base64' guidance in the description foreshadows and reinforces the schema's image_urls note, adding operational meaning the schema alone would not convey.
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-plus-resource statement: 'open, check, and resolve disputes on orders the user BOUGHT.' It sharply differentiates itself from firestarter_seller_disputes by naming the sibling and stating 'This is the BUYER side,' so an agent can distinguish the two without needing to inspect their schemas.
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 triggers ('Use this whenever a buyer asks...') with concrete examples like 'item never arrived, arrived damaged / wrong / not as described'), enumerates the exact actions available (post a note, accept/reject/counter, withdraw, escalate), and gives a clear exclusion: 'for disputes on orders the user is SELLING, use firestarter_seller_disputes instead.' The when and when-not guidance is complete.
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 show destructiveHint:true, but the description adds valuable behavioral context: past credit still clears, only future activity stops, and this is an account-level change. This helps the agent understand exactly what will and won't be affected, going beyond the raw annotation flags.
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 core action and purpose. Every sentence adds information: the first states the action and consequence, the second covers the temporal nuance and scope. 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?
For a zero-parameter tool with no output schema, the description covers the action, use case, and long-term effects. It leaves out only minor details like reversibility or whether the buyer remains a member of the market, but these are not necessary for calling 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?
The input schema has zero properties, so there is nothing for the description to add. Baseline for 0 params is 4; the description doesn't need to explain parameters and doesn't mention any, which is consistent.
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 ('Disconnect') with a clear resource ('buyer from their current community market') and states the effect ('future orders no longer credit it'). It distinguishes itself from sibling tools by its focus on removing the link, not updating or joining a market.
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 when to use ('Use when a buyer asks to leave/disconnect a community, or wants to switch to another one') and clarifies the nuance about past vs. future credit. However, it does not name specific alternative tools or state explicit 'when not to use' conditions, 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 declare readOnlyHint=true and destructiveHint=false, and the description's 'Read-only' statement reinforces rather than contradicts them. The description adds genuine context beyond the annotations: the full return payload (id, discount, claimed vs cap, status), the full status enum with the pending_seller_approval edge case spelled out, and the integration note that the drop id feeds firestarter_cancel_drop. Deducting one point because the basic read-only guarantee is already carried by annotations, so the description's marginal contribution, while good, is not exceptional.
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?
Packs a complete mental model — ownership scope, return fields, status semantics, cancel flow, usage triggers, and sibling distinction — into ~150 words with no padding. Front-loads the most critical differentiator (OWN) and keeps the alternative-tool handoff to a single compact sentence at the end. Withholds a perfect score only because 'Read-only' and the phrase 'a drop on another seller's listing' restate, respectively, what the annotations and earlier clauses already establish.
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 filter tool with one parameter and no output schema, the description is exhaustive: it covers the return shape, all possible status values including the edge case, the cross-tool id contract, example queries, and the sibling-vs-owner boundary. There is no output schema to compensate for, and the description leaves nothing material unexplained for an agent to invoke this 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 coverage is 100% — the single program_id parameter is already documented as 'The market/program id you own (from firestarter_my_markets).' The description echoes and enriches this by centering the ownership constraint ('on a market you OWN') and explaining what the returned data looks like (claimed vs cap, status, listing, tier gate, expiry), which helps an agent reason about the parameter without re-stating its syntax. Baseline 3 at full coverage, and the description earns one extra point by clarifying ownership semantics that the param schema names 'market/program' — a noun the description resolves.
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?
Specifies a clear verb+resource ('List the community-sponsored drops on a market you OWN') with an explicit parenthetical tying it to firestarter_create_drop. It distinguishes itself from its sibling firestarter_drops ('This is the OWNER view; buyers discover... with firestarter_drops'), leaving no ambiguity about which of the two drop-related read tools applies.
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 triggering conditions with natural-language quotes: "'how are my drops doing?', 'how many people claimed my drop?', or wants to see what drops are still live before creating another." It also names the exact alternate tool (firestarter_drops) to use instead when the user is a buyer, and references firestarter_cancel_drop for the id handoff, giving the agent a full decision tree for routing.
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 annotations already mark it read-only, open-world, and non-destructive, and the description adds substantial behavioral context: it shows the signed-out visitor view, lists both market surfaces, notes that listing_ids are accepted by firestarter_execute, and explicitly debunks the assumption that joining grants discounts or cashback. This goes well beyond the annotation signal 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and returns, then proceeds to usage and expectations. It is longer than strictly necessary, especially the detailed fee/discount explanation, but every sentence carries behavioral or routing value and there is 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?
For a one-parameter read-only preview with an output schema present, the description covers when to call it, what it returns, how the result connects to purchase via listing_id, and the key caveats about joining and discounts. An agent has enough context to invoke it correctly and interpret the result appropriately.
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 the schema parameter already explains that `code` is 'The community's share code or vanity handle'. The description repeats this idea and gives the URL context, but does not add material new semantics beyond what the schema already provides, so the high-coverage 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: 'Preview a community market BEFORE joining', with a precise output contract (name, tagline, curated shelf, own listings). It also names the handle-based URL and distinguishes the read-only preview from the separate join step, so an agent can tell this apart from firestarter_join_market and firestarter_preview.
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 when to use the tool: 'Use when a buyer pastes a market code/link or asks ...'. It also clarifies when not to treat joining as required, noting that items are buyable without joining and that joining is a separate optional step, which prevents the agent from calling firestarter_join_market unnecessarily.
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 destructiveHint=false, so the description's closing 'Read-only' is somewhat redundant. However, it adds genuinely useful behavioral context beyond annotations: the '(if any)' caveat signals that no market may exist, and the 'buyable via firestarter_execute' line tells the agent how to proceed after seeing products. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose leads, followed by trigger examples and the read-only tag. It is one compact block with no filler, though the long first sentence with em-dashes and a parenthetical is slightly run-on. The trigger-list sentence is helpful enough to justify its length.
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?
Has a true output schema, so return values need no description. For a parameterless read tool, the description covers purpose, when to call, edge cases ('if any'), and the follow-up buy action via firestarter_execute. Nothing an agent needs to select and call it correctly 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?
There are zero parameters, so the baseline is 4 — the description cannot add parameter-specific meaning. Instead it wisely documents what the output contains (community name, join code, status, curated picks, listings), which serves the agent better than parameter detail would 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 uses a specific verb-resource pair ('Show which community market the buyer is currently connected to') and enumerates the exact data returned: community name, join code, program status, curated shelf, and listings. It implicitly distinguishes itself from siblings like firestarter_my_markets (plural, listing all markets) by emphasizing 'currently connected to' — an agent can tell it apart without opening any sibling schema.
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 trigger phrases ('what market am I in?', 'am I connected to a community?', 'what can I buy here?') and a clear temporal use case (before joining/leaving to confirm current state). This is as concrete as usage guidance gets — the agent knows exactly which buyer intents route here.
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 indicate readOnlyHint=false and destructiveHint=false, so the description carries the burden of behavioral clarity. It discloses that the tool returns a 'no-login Stripe setup link (works from any channel) plus a dashboard link,' and clarifies its role in the purchase funnel. While it doesn't explicitly list side effects (e.g., whether it creates a Stripe session), it doesn't mislead and adds meaningful 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively long (~150 words) but every sentence earns its place: it front-loads the primary action, then explains context, triggers, and return values. While it could be tightened, the structure is logical and non-redundant.
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 tool with no parameters and no output schema, the description is complete: it covers purpose, when to use, what it returns, and how it fits among many siblings. The agent has all necessary information to decide when to call it and what to expect.
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 doesn't need to explain parameter usage, and it doesn't attempt to. No gaps exist in this dimension.
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 clear, specific purpose: 'Check the buyer's payment method status and get a link to add or update their card.' It distinguishes this from sibling tools by explicitly positioning it as the last step of a purchase and naming related tools (firestarter_execute, shipping_option_index) in the context. No ambiguity remains about what this 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: 'Use this tool when the buyer asks about payment or an order is waiting on a card.' It also clarifies when NOT to use it (browsing, quoting, comparing never require a card) and contrasts it with other tools in the purchase flow. The guidance is unambiguous and prescriptive.
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 annotations by explaining the semantics of 'unknown' for Stripe, the authoritative nature of PayPal's list, and the real-world consequences of selling in an unsupported country (escrow, eventual pause). These are behavioral nuances that readOnly/idempotent hints do not convey.
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 long but front-loaded with the core purpose and contains important caveats that earn their place. A small amount of redundancy ('which is exactly why checking first is worth it') keeps it from being perfectly concise, but the structure is logical.
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 still conveys what the result will contain (per-rail verdicts) and how to interpret the two key outcomes. It also covers downstream consequences and points to the right sibling tool for thresholds, making it self-sufficient 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?
The single parameter 'country' already has a complete schema description with format and examples, so the description adds little beyond restating that it takes a country code. Baseline 3 is appropriate because schema coverage is 100%.
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: 'Check whether Firestarter can pay a seller in a given country', takes an ISO country code, and returns a per-rail verdict. It also distinguishes itself by noting no seller account is required and by contrasting with related operations such as firestarter_payouts.
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 tied to concrete triggers: 'whenever someone asks can I sell on Firestarter from <country>' or before walking a seller through registration. It also names an alternative, firestarter_payouts, for current thresholds, and explains why checking first is valuable.
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 destructiveHint=false, so the description's 'Read-only' statement adds little beyond annotations. However, it adds useful context about the listing_id format (lst_...) and that it can be parsed from share links, which is beyond the schema. It also clarifies the tool does not handle buying or shipping, which is helpful. 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 sentences, front-loaded with the core purpose, and every clause adds value. It efficiently covers purpose, usage context, and next steps 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 the tool's simplicity (one parameter, no output schema), the description is complete. It covers what the tool returns (full detail), how to use it, and what to do next. The only minor gap is not describing the output structure, but with no output schema, the description's list of fields (photos, description, attributes, etc.) suffices.
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 100% for the single parameter, so the schema already documents listing_id. The description adds value by explaining the format (lst_...) and sources (catalog search, preview, share link), which goes beyond the schema's description. This is a good enhancement.
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 shows one product in full detail, listing specific content (photos, description, attributes, price, buyability, seller trust profile). It explicitly positions it as the buyer's zoom-in after catalog search or preview, distinguishing it from siblings like firestarter_preview and firestarter_catalog_search.
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 when-to-use guidance: after firestarter_catalog_search or firestarter_preview. It also names alternatives for next steps: firestarter_execute for buying, firestarter_shipping_estimate for shipping quotes. This clearly differentiates from siblings and gives a workflow 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?
Annotations already provide readOnlyHint=true and destructiveHint=false, and the description adds value beyond them by disclosing the precondition (payment must be complete after firestarter_approve) and the common failure mode (no receipt before payment). It doesn't cover error behavior for invalid/unknown execution IDs or whether receipts are re-fetchable, but for a simple read-only tool the key behaviors 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?
Four clean, front-loaded sentences with zero filler. The purpose and precondition come first, return format second, and alternative routing last. Every sentence earns its place with information the agent needs, and no sentence is wasted on the already-known.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (1 param, no output schema), and the description covers purpose, the meaning of the parameter, return format, negative case, and sibling alternatives. Since there is no output schema, the description appropriately covers the return values. Minor gaps remain for edge-case error responses or permission failures, but the description is largely complete for a basic read 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 coverage is 100%, so the schema documents execution_id with format 'exec_...'. The description adds extra meaning by tying the parameter lifecycle: the ID must reference an order that has the buyer already paid for it, which narrows the parameter's semantic meaning. With the baseline of 3 for high schema coverage, the added context on preconditions for passing it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get the payment receipt for an order the buyer has already paid for.' It clearly distinguishes from siblings by name (firestarter_status, firestarter_track_order, firestarter_return), making the tool's role unambiguous. The title 'Get Receipt' in annotations adds further clarity.
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 says when to use it — 'whenever the buyer asks for a receipt, invoice, proof of payment, or expense documentation' — and when not to: 'If the order hasn't been paid yet, there's no receipt: check firestarter_status instead.' It names concrete alternatives for delivery tracking and returns, leaving nothing to inference.
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 provide readOnlyHint: false, so the description correctly implies mutation. The description adds meaningful behavioral context beyond annotations: the three-form behavior, the primary-origin semantics ('the primary drives every quote's origin'), and the country-specific requirements. It doesn't address edge cases like what happens on overwrite or partial failures, but for an idempotent-looking save operation, this is solid. Minor deduction: it doesn't warn about potential side effects like changing the origin for existing quotes, but the primary emphasis mitigates that.
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 dense but efficient. It front-loads the core purpose, then packs the three operational forms into three parenthetical clauses, then adds the primary key insight. Every sentence adds information; no filler. The structure mirrors the decision an agent must make (create vs update vs promote) in the same order, making it 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?
Given 10 parameters, full schema coverage, no output schema, and a sibling list that includes firestarter_delete_ship_from and firestarter_ship_from_locations, this description covers the essentials. It explains the three forms, primary semantics, and restrictions. It could note that the response is likely the saved location or an error, but without an output schema, that's a minor gap. It also doesn't mention authorization beyond 'Seller accounts only' — but that's a small omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each of the 10 parameters is already documented in the schema. The description adds cross-parameter relationships (e.g., street1 + city required when creating, state/zip required for US/CA/AU, location_id or omit to create) that the individual schema descriptions lack. It also clarifies the role of is_primary ('Set is_primary on the address parcels actually dispatch from — the primary drives every quote's origin.'). This exceeds the baseline 3 for full coverage by explaining interaction between parameters and conditional requirements.
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: 'Add or update a seller ship-from (fulfillment) location — the address shipping rates are quoted FROM.' It uses a specific verb-resource pair and immediately distinguishes the ship-from tool from its sibling firestarter_save_address (which likely handles buyer/seller addresses) and firestarter_ship_from_locations (a read/list tool). The three operational forms enumerate exactly what the tool does, leaving no ambiguity about create vs update vs promote-to-primary.
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 breaks down three usage forms with clear conditions: (1) no location_id → create, (2) location_id + address fields → update, (3) location_id + is_primary true and no address fields → promote. It also states the requirement for US/CA/AU origins (state/zip required) and the seller-only restriction. This is more than enough for an agent to decide when to invoke and how to structure arguments.
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 destructiveHint=false, so the description's 'Read-only: never changes anything' is redundant but harmless. It adds value by disclosing that each order line carries the order_id used in confirm/ship and that the tool covers Shopify orders, expanding beyond the annotation's generic read-only flag.
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 about three sentences long and front-loads the core purpose and fields. It includes the fulfillment flow, usage triggers, and a read-only note without fluff. Each sentence earns its place, though the flow description could be seen as slightly beyond the minimal scope.
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 to rely on, the description covers what fields are returned, how to use the result (order_id for follow-ups), the coverage of Shopify, and reinforces the read-only nature. For a zero-parameter list tool, this is sufficient for an agent to call it correctly and understand its role in the larger workflow.
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 is empty (0 parameters), so there is nothing to explain. Per the rubric, 0 params gets a baseline of 4. The description adds no parameter details because none exist; it focuses on output and usage, which 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: 'View the seller's incoming orders' and enumerates the exact fields returned (product, quantity, amount, net payout, order status, payout status, carrier tracking). It also implicitly distinguishes itself from siblings by positioning itself at the start of the fulfillment flow, which is unique in the large 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use this tool: 'Use whenever a seller asks about their orders, sales, what sold, or recent activity.' It also maps the flow to the two follow-up tools (confirm_order and ship_order) and notes it covers Shopify orders, giving the agent clear routing guidance without needing to open other tool schemas.
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=false and destructiveHint=false, covering the mutation and non-destructive nature. The description adds valuable behavioral context: handle stability across share-code rotation, resolution equivalence, and uniqueness enforcement. It does not describe what happens to the old handle after a rename, but that is minor given the annotation 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 pack the entire purpose, usage, and a key constraint with zero redundancy. The action is front-loaded, and every clause earns its place. 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 2-parameter tool with no output schema, the description covers the core operational details: ownership prerequisite, use case, stability, and uniqueness rejection. It might benefit from noting whether the handle change is reversible or affects existing links, but these are minor given the annotation safety hints and schema completeness.
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% with detailed descriptions for both handle and program_id, so baseline is 3. The description adds meaning by clarifying the relationship: program_id comes from firestarter_create_market, and handle's stability and uniqueness are reinforced. This bridges the parameters to the tool's purpose beyond what the schema states.
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: 'Claim or change the vanity handle for a market you already own'. It clearly states the outcome (URL becomes firestarter.network/m/<handle>) and distinguishes this from related sibling tools like firestarter_create_market (creating a market) or firestarter_update_market (other settings). The mention of 'from firestarter_create_market' anchors its dependency without ambiguity.
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 states when to use: 'Use when an owner wants a memorable community link, or to rename an existing handle.' It also provides a hard constraint ('must be unique across Firestarter' and rejection conditions) which guides the agent in anticipating failures. While it doesn't enumerate alternatives, the use-case framing is precise and self-contained.
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?
Adds significant behavioral details beyond the annotations: the 30-day no-demotion grace period, that tiers are derived from qualifying orders with no per-member storage, and that turning tiers off is possible. These are non-obvious side effects not captured by readOnlyHint or destructiveHint.
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 detailed but not wasteful; every sentence adds context about purpose, behavior, or defaults. It is well-structured, though slightly longer than necessary, but remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the tool's purpose, how tiers work, defaults, the ability to add/rename rungs, and crucial behavioral nuance. Since there is no output schema, explaining return values is not required. The description is self-contained and sufficient for an agent to decide when and how to use 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% with descriptive parameter comments, but the tool description enriches meaning by explaining the tier system (access, not money) and the effect of raising thresholds (e.g., no immediate demotion). This goes beyond the schema's field-level descriptions.
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?
Clearly states the verb 'configure' and resource 'member tiers' for a community market, and differentiates from the sibling firestarter_set_market_picks by explaining the tier-access relationship. The description makes the tool's purpose 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 implies when to use the tool (to customize tier rungs, thresholds, or disable tiers) and mentions that defaults exist, so it may be optional. However, it does not explicitly contrast with alternatives despite referencing set_market_picks. Still, the context is clear enough.
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 communicate that this is not read-only and is potentially destructive, but the description adds genuinely useful behavior: disable:true removes the cap entirely, and a purchase previously rejected with SPEND_CAP_EXCEEDED will succeed after the cap is raised and the purchase retried. This is meaningful operational 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 main action is front-loaded, and every sentence adds distinct value: intent paraphrases, the SPEND_CAP_EXCEEDED workflow, the disable path, and the read-only sibling. It is thorough without being padded, and the detail is justified by ambiguity in natural-language requests.
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 three-parameter, optional output-less mutation tool, the description is very complete: action variants, retry semantics, disable behavior, and the read sibling are all present. It loses one point for not addressing the combination of disable:true together with spend_cap_dollars, and for leaving alert_threshold_pct to be discovered solely through the 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 100%, with each parameter already well documented. The description adds only a natural-language example ($100) and tells the agent use disable:true to remove the cap, but it does not materially expand the parameter 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 is action-first: 'Raise, lower, set, or remove the buyer's monthly spend cap' and gives concrete user phrase examples. It also explicitly contrasts with the sibling firestarter_spend_cap by saying that tool is for reading the current value, so the boundaries are 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?
It explicitly states when to use this tool: whenever the user wants to increase, raise, set, lower, or change the cap. It also defines the SPEND_CAP_EXCEEDED flow, where raising the cap here lets a rejected purchase go through on retry, and tells the agent to use firestarter_spend_cap for read-only lookups.
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 destructiveHint annotations, the description adds rich behavioral context: it reports the current environment (test vs live) and the account the API key belongs to, explains the test mode with fs_test_ vs fs_live_ keys, and notes that the mode is fixed by the key, not a per-call option. This goes far 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose and then explains environment/test mode. It is more verbose than necessary but each segment adds value — the test-mode explanation is critical for correct interpretation. It is well-structured but could be tightened with bullet points. Not as concise as the ideal, but not bloated.
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 status tool with no output schema, the description is complete: it covers the primary function, optional parameters, environment/account details, test-mode behavior, and the no-argument invocation for the summary. An agent has everything needed to call it correctly and interpret 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 100%, so baseline is 3. The description adds a crucial usage note: 'call it with no arguments for the environment + account summary.' This clarifies the optionality of parameters beyond the schema, which only lists them as optional. It also implicitly connects execution_id to 'check one order' and status_filter to 'list recent orders'. This exceeds the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb-resource pair: 'check the buyer's ORDER HISTORY and order status on Firestarter.' It clearly distinguishes buyer-side order viewing from seller-side (firestarter_seller_orders) and adds environment/account reporting. The purpose is unambiguous and differentiates from tracking-specific siblings like firestarter_track_order.
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 usage context: 'Use this to check on orders, see what options were found, get tracking updates, confirm whether you are in test/sandbox mode, or answer which account/user am I operating as?' This is clear context, but it does not name alternatives or state when not to use it. Lacks explicit exclusions, so not 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?
Annotations mark readOnlyHint=false and destructiveHint=false, and the description adds valuable behavioral detail beyond those flags: 'Syncing runs in the background and returns immediately,' 'products appear in firestarter_listings once the sync completes,' and it 'never changes the seller's Shopify store.' This clearly sets expectations for side effects, timing, and mutation scope 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 front-loaded with purpose and then methodically covers triggers, prerequisite, async behavior, side-effect scope, and parameter usage. Every sentence adds distinct information—no filler or repetition—and the structure makes the tool's behavior easy to parse quickly.
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 explains the immediate return behavior and where results materialize ('appear in firestarter_listings once the sync completes'), which is sufficient for an agent to act on. It also covers prerequisites and side effects, though it does not specify the exact immediate response payload (e.g., whether a sync job ID is returned), leaving a minor gap.
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 documents connection_id with 100% coverage, including its optionality and disambiguation purpose. The description's parameter guidance ('By default it syncs the seller's connected Shopify store; pass connection_id to target a specific connection') reinforces the schema but adds no genuinely new semantic detail, 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 names a specific verb and resource ('Re-sync a connected store's catalog into Firestarter') and specifies the data affected (products, prices, inventory). It also differentiates itself from siblings by referencing firestarter_connect_shopify (creates the connection) and firestarter_listings (where refreshed products appear).
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 trigger conditions: 'seller says they added/edited/removed products, prices look stale, a previous sync errored, or items aren't appearing.' It also states the prerequisite of an already-connected store and points to firestarter_connect_shopify as the alternative for creating the connection, plus parameter guidance for connection_id when multiple platforms are linked.
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 only say the tool is not read-only and not destructive. The description goes well beyond that by disclosing: standing approval is durable, pending requests are auto-approved, revocation only affects new requests, already-live drops remain, and discount costs still come from proceeds. That is strong 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well organized: primary effect, triggering condition, reversal, caveat. It is slightly verbose and repeats the immediacy concept a few times, but every sentence contributes a meaningful behavioral point.
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 state-changing tool with no output schema, this is nearly complete. It covers what the tool does, when to use it, what happens to pending requests, how to revoke it, the scope of revocation, and the financial consequence.
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 input schema explains program_id as the id from firestarter_drop_requests or the community owner. The description itself adds no extra parameter-level detail, so the 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?
The description explicitly states the verb and resource: 'Grant a community program standing approval to run drops on your listings.' It clearly distinguishes this from per-request approval tools and from the revocation tool firestarter_untrust_community_drops.
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 an explicit adoption condition — 'once you're comfortable a community's asks are reasonable' — and names the alternative for reversing the action. It tells the agent both when to use the tool and what the untrust sibling does differently.
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 destructiveHint=false, and the description does not contradict them. It adds context by explaining what the balance includes (spendable, reserved against live self-funded drops, spent, lifetime totals), which is behavioral information beyond the bare annotation. The explicit 'Read-only' marker is somewhat redundant with the annotation, but the component breakdown adds genuine value. A minor gap: it doesn't describe the exact response structure, but with no output schema that's acceptable.
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 a clear front-loaded purpose followed by enumerated components. It is slightly longer than strictly necessary, but every clause adds meaning and the structure is logical. The usage guidance is placed at the end, which is fine because the core purpose comes first.
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, read-only tool with safety annotations already covering the behavioral profile, this description is complete. It fully explains what the balance shows, when to use it, and how it relates to funding and withdrawal. No critical information is missing 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?
The tool has zero parameters, so the description carries no parameter documentation burden. Schema coverage is 100% (empty schema). The baseline for 0 params is 4, and the description does not need to add parameter semantics. It correctly focuses on output semantics instead.
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 clear verb-object pair ('Show your drop wallet's balance') and enumerates the specific components of that balance (spendable, reserved, spent, lifetime totals). This uniquely identifies the tool and distinguishes it from financial siblings like firestarter_withdraw_wallet and firestarter_fund_wallet. An agent cannot confuse it with any of the 80+ 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states three trigger conditions: 'when an owner asks what's in their drop wallet', 'before firestarter_withdraw_wallet', and 'to check whether a firestarter_fund_wallet deposit has cleared yet'. It also names two sibling tools directly, giving concrete routing guidance. This is exactly the level of usage differentiation expected.
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 flag destructiveHint:true and idempotentHint:false. The description goes far beyond by explaining the non-idempotency in detail (each call is independent, retries withdraw twice), and how to resolve uncertain outcomes via firestarter_wallet_balance. It also warns about the spendable-only constraint. This is substantial added value over 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but every sentence is purposeful. It front-loads the core action, then adds the spendable split, minimum, and the non-idempotency warning. Structure is logical, though it could be slightly tightened without losing value. It is verbose but not bloated.
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 non-idempotent, destructive financial operation, the description covers all necessary ground: purpose, prerequisites, eligibility, minimum, risk of retries, and how to verify success. It references related tools (connect_payouts, wallet_balance) and explains behavior comprehensively. No output schema exists, but the description explains how to confirm the outcome.
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% and includes the minimum and unit. The description reinforces the $1.00 minimum and adds the critical constraint that only the spendable balance is withdrawable, which directly informs how to choose the amount_cents. It also implies checking wallet_balance first. While not adding syntax, it adds practical validation 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 states a specific verb ('Cash out'), a resource ('unused drop-wallet balance'), and a destination ('connected Stripe payout account'), and even names the prerequisite tool (firestarter_connect_payouts). It also differentiates from related siblings like firestarter_wallet_balance, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides strong context on when to use the tool: after connecting payouts, and it references firestarter_wallet_balance to identify the spendable amount. It also clarifies what cannot be withdrawn (reserved funds). However, it does not explicitly state alternatives like 'use firestarter_fund_wallet for depositing' or 'do not use this for refunds', but the context is embedded well enough for an agent to infer.
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, destructiveHint=false, and openWorldHint=false. The description adds valuable context beyond annotations: it explains the real stored account setting nature, the auto-approval behavior threshold, and persistence. This is a strong addition, but the description could have further detailed the exact return format or value representation, which is absent. However, given annotations cover safety, a 4 is appropriate.
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: it opens with the core purpose, then explains the behavior and scope, and ends with a clear pointer to the sibling tool. Every sentence adds value: the behavior, persistence, applicability, and read-only note. No waste 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 the tool is read-only with no output schema and two ignored parameters, the description is complete: it defines what the limit is, how it behaves, where it applies, and directs to the write tool. An agent has all necessary information to call this tool correctly without opening 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 100% with descriptions for both parameters stating they are ignored and redirecting to the write tool. The description reinforces this by saying 'Read-only: use firestarter_set_auto_approve_limit to change or disable it.' The description adds value by clarifying the read-only nature beyond the schema, but since the schema already explains the parameters fully, baseline is 3, and this adds a bit more context, so 4 is justified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads the buyer's persistent account-level auto-approval limit, distinguishing it as a read operation. It explains the semantics of the limit (at or below auto-approved, above pauses) and differentiates from the sibling tool firestarter_set_auto_approve_limit by explicitly naming it as the write counterpart.
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 this tool (read the current limit) and when not to (change or disable it, using firestarter_set_auto_approve_limit instead). It names the alternative tool directly and provides context that the setting persists until changed, clarifying its scope across all surfaces.
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 implies a write operation (connecting a store) and describes a two-step flow: checking for existing connections and then providing credentials. While it doesn't explicitly state side effects like creating or updating a connection, the term 'connect' conveys the primary behavior, and the annotations (readOnlyHint=false) already signal a non-read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and free of redundant information. Each sentence serves a purpose: listing supported platforms, pointing out alternative tools, and outlining the two-step calling convention. No unnecessary verbosity.
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 description is self-contained: it identifies supported platforms, differentiates from sibling tools, and explains the invocation pattern. It covers the essential steps and parameter usage without requiring additional context. The lack of an output schema is acceptable since the tool's primary purpose (connecting) and its two-phase flow are clearly communicated.
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 describes four of five parameters (shop_domain, access_token, consumer_key, consumer_secret) with meaningful details. The description adds context for the `platform` parameter by explaining that it can be used alone initially to retrieve credential instructions or check existing connections, filling a gap in the schema's own 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 clearly states the action (connect a store) and specifies the supported platforms (BigCommerce, Shopee, Lazada, Wix, WooCommerce). It also explicitly excludes Shopify and TikTok, directing users to dedicated tools, 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?
The description provides explicit instructions on when to call with only the platform (to check for existing connections or get credential instructions) versus when to call with full credentials. It also references sibling tools for Shopify and TikTok, ensuring correct tool 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 destructiveHint=false, so the description does not need to repeat safety. But the description adds crucial behavioral context: it reveals the requests are invisible to buyers and unclaimable until acted upon, and that they can expire on their own. It also discloses the content of the list (requesting community, listing, discount, claim count, deadline). This goes beyond annotations and helps the agent understand the state of the world, though it could mention what happens after expiry more explicitly.
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, dense paragraph that is front-loaded with the purpose and key constraints. Every sentence adds information: scope, behavior, content, and next steps. It avoids fluff and is well-structured for an agent to parse.
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, no output schema, and annotations cover safety, the description is complete for an agent to know what it does, when to use it, and what it returns. It even gives the call IDs (drop id) for follow-up tools. Nothing essential 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 0 parameters, and schema description coverage is 100%, so there is nothing to add. The description explains what the tool returns (the list of requests with specific fields), which is more valuable than parameter semantics. A baseline 4 is appropriate for tools with no parameters that clearly describe their output.
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 the community-sponsored drop requests waiting on YOUR decision as a seller'), and clearly differentiates from siblings like firestarter_approve_drop, firestarter_reject_drop, and firestarter_trust_community_drops. It fully explains the context and purpose of the tool, which is more than just restating the name.
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 says when to use this tool (to review requests waiting on your decision) and names alternatives (firestarter_approve_drop, firestarter_reject_drop, firestarter_trust_community_drops) for subsequent actions. It also states the condition (a community owner proposes a per-claim discount on one of your listings) and what the tool shows. This is strong guidance for an agent to choose and invoke it correctly.
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 far beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true). It discloses the go-live-vs-draft activation gate (e.g., NEEDS_IMAGE with allow_imageless override), the full default set when fields are omitted (unlimited inventory, live shipping estimates, account default ship-from, worldwide shipping), the duties disclosure for cross-border buyers, deprecated shipping behavior, source_url best-effort enrichment that never overwrites explicit values, and video re-hosting semantics. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but earned: it front-loads purpose and the required-only contract, then covers defaults, activation behavior, image workflow, and sibling routing in dense prose. The one mildly redundant passage is the enumeration of optional settable fields ('brand, condition, sku...'), which the schema already documents, but it serves as a useful orientation checklist for a 29-parameter tool, so it is not wasted.
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 complex tool with 29 parameters, nested objects, and no output schema, the description covers the critical non-obvious behaviors: the live-vs-draft activation outcome and that the response lists what to fix, the 'response echoes the resulting settings' return expectation, the upload-image prerequisite, and the source_url fill-in behavior. It leaves minor gaps such as validation-failure handling for malformed shipping_policy or ship_from objects, but the schema enums and per-field descriptions fill most of those, making this substantially 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?
Schema coverage is 100%, so the baseline is 3, but the description adds genuine cross-parameter meaning: it elevates product_name and base_price as the only required fields, explains default behavior for omitted inventory/shipping/ship-from/shipping_policy, clarifies the image_urls workflow dependency on firestarter_upload_image, and flags the shipping field as deprecated/ignored. These are semantics the schema descriptions do not convey on their own, though the heavy lifting for individual parameters still falls 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 opens with a specific verb+resource pair ('List (create) a product for sale on Firestarter') and immediately constrains scope to the two required fields. It explicitly distinguishes itself from siblings by naming firestarter_listings (view), firestarter_update_listing (edit), and firestarter_catalog_search (browse others' products), so an agent cannot confuse it with adjacent tools even without opening their schemas.
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 routing: use firestarter_listings to view, firestarter_update_listing to edit/refine later, firestarter_catalog_search to browse other sellers, and firestarter_upload_image FIRST when a conversation photo needs a permanent URL. It also clarifies when to pass allow_imageless and allow_duplicate (only on seller confirmation), which is actionable selection guidance beyond the schema.
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 include readOnlyHint=true and destructiveHint=false; the description reinforces this with 'Read-only.' It adds context about the ownership scope (only markets the user created) and the fields returned, which goes beyond the annotations but does not disclose additional operational behavior (e.g., auth details, 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 yet information-dense: it opens with the core function and fields, then immediately offers usage guidance and alternatives. Every sentence serves a purpose 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?
Given no output schema, the description fully covers the return structure and the intended usage. It also clarifies ownership and read-only nature, and points to related tools for adjacent needs, making it complete 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so the baseline is 4. The description implies no inputs are needed by stating 'List the community markets you OWN' without mentioning any configuration options. No additional parameter explanation 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 clearly states the action (List) and the resource (community markets the user owns), and enumerates the exact fields returned (program id, buyer-facing name, URL/handle, share code, status, fee share, member count). It also differentiates from siblings by naming specific alternative tools (firestarter_market_earnings, firestarter_market_preview) and their use cases.
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 scenarios ('what markets do I have?', needing program_id, at-a-glance view) and explicitly names alternatives for earnings and preview. The read-only note further clarifies safe 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 signal destructiveHint=true and readOnlyHint=false, and the description adds meaningful context beyond that: refund 'lift[s] the escrow freeze', contest 'reject[s] the claim', and split proposes a partial refund. It also clarifies the non-destructive read paths (list and read thread). It stops short of fully describing outcome/irreversibility, but the annotations cover 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph, but it is front-loaded with the core purpose and sibling distinction before diving into call patterns. Every sentence carries operational value, though a bulleted structure for the four actions would improve scanability.
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 tool with no output schema, the description explains the return behavior for list (each dispute shows its dispute_id) and for read (full thread with buyer claim and photos). It covers all call modes, all actions, parameter constraints, and the key alternative tool. Nothing essential is missing 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.
Parameters5/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, but the description adds significant extra semantics: no-args lists disputes, dispute_id alone reads the thread, image_urls should carry a packing shot, and split requires buyer_pct + seller_pct = 100. It also warns against converting images to base64, which is practical guidance not present in 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 names a specific verb and resource: 'View and resolve disputes on orders the user is SELLING', and immediately scopes it as 'the SELLER side only'. It also distinguishes itself from the sibling firestarter_disputes by contrasting seller-side versus buyer-side disputes, so an agent can tell them apart without parsing schemas.
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 when to use this tool ('when a seller mentions a dispute, complaint, refund, chargeback, or return on something they sell') and when not to ('if the user is asking about something they BOUGHT... use firestarter_disputes instead'). It also gives clear call patterns: no args to list, dispute_id alone to read, and action plus parameters to act.
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 destructiveHint=false, and the description adds 'Seller accounts only' and explains the primary location's role in shipping quotes. For a simple list with no output schema, this provides sufficient 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?
Three sentences with the core action front-loaded, followed by important context and then alternative tools. Every sentence serves a purpose 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 zero-parameter read-only listing tool, the description covers purpose, scope, seller-only restriction, and connections to sibling tools. No additional information is necessary for an agent to call 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?
The tool has zero parameters, so the baseline is 4. The description adds domain context about the primary location affecting quote pricing, which aids interpretation of the returned list even though no parameter specifics are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and resource 'seller's ship-from locations', clearly distinguishing it from save/delete siblings. It also explains the primary location's significance, leaving no ambiguity about 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly names firestarter_save_ship_from for add/correct and firestarter_delete_ship_from for removal, providing clear alternatives. The statement 'Seller accounts only' also establishes a usage condition.
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 this as a non-read-only, non-destructive action. The description adds useful side effects beyond the annotations: the buyer is notified automatically, tracking becomes available to the buyer, and carrier defaults to USPS. It does not discuss reversibility, but the annotation plus side-effect context 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 compact and front-loaded: core action, required fields, and default behavior appear immediately. The subsequent sentences each add distinct value—flow context, timing, side effects, and an id warning—without repetition 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 three-parameter mutation with no output schema, the description covers the complete invocation decision: which flow step this is, when to call it, required parameters, carrier default, buyer-side side effects, and exactly where order_id comes from. Nothing essential to invoking it correctly 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?
Schema coverage is 100%, so the schema already documents all parameters. The description adds real semantic value by emphasizing that only order_id and tracking_number are required, that carrier is optional and defaults to USPS, and that order_id must be the seller-facing id rather than the exec_... execution id.
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 names the exact action ('Mark an order shipped'), the object (order), and required data (carrier and tracking number). It also positions the tool as the terminal step of a named fulfillment sequence, making it distinguishable from siblings like firestarter_confirm_order and firestarter_track_order.
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 call it: 'Call once the seller has actually handed the package to the carrier and has a tracking number.' It also places it after firestarter_confirm_order and notes that no separate buyer message is needed, steering the agent away from firestarter_message.
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 (destructiveHint, readOnlyHint=false), the description discloses critical behavioral traits: it actually executes a financial transaction and pays, uses the buyer's saved default address automatically, handles price changes via a nonce-based confirmation flow, resolves a single pending purchase automatically, and rejects non-purchasable items. It also details the consequence of no saved address ('approval of physical goods is rejected'). All traits are consistent with the destructiveHint annotation; there is 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-organized: it front-loads the core purpose and then systematically covers lifecycle, address handling, option selection, shipping, price changes, and edge cases. Each paragraph addresses a distinct concern, and every sentence contributes concrete operational detail. While it could be trimmed slightly, the density is justified given the tool's complexity (8 parameters, multiple fallback behaviors). It earns its length.
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 nearly every operational scenario an agent might face: missing address, price-change confirmation, auto-resolving single pending orders, multiple pending candidates, informational vs. purchasable options, and shipping-speed selection. It references response elements like PRICE_CHANGED and masked ship-to views, but does not fully specify the successful response structure (e.g., order confirmation details). Given the absence of an output schema, a bit more detail on the exact success response would round it out, but the coverage is already substantial 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.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds substantial semantic depth beyond schema entries. For example, it explains that option_id is preferred because it 'identifies the product itself rather than a position that can shift,' warns never to guess confirm_total, stresses consent_nonce is single-use and echoed verbatim, clarifies delivery_address can be a string or object and that it's saved as default on first orders, and details shipping_option_index semantics. This guidance is essential for correct invocation and goes far beyond the schema's already-descriptive parameter definitions.
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 clear, action-oriented statement: 'Confirm and place an order that is awaiting approval — this is the step that actually BUYS and pays.' It explicitly names the resource (an order awaiting approval) and distinguishes the tool from siblings like firestarter_execute (which returns options) and firestarter_receipt/track_order (post-purchase steps). The lifecycle context reinforces the unique purpose.
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 sequences usage: after firestarter_execute or a listing_id buy returns options, this tool places and pays; afterwards use receipt and track. It also gives clear when-not guidance: 'Only Firestarter-purchasable options can be approved — browse-only results are rejected.' It explains when to omit execution_id and how the tool resolves pending purchases, and when to use option_id vs selected_option, plus when to pass delivery_address/address_id. This is comprehensive and leaves little to inference.
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 write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds critical behavioral context beyond these: batch size limit (100 per call), non-atomic partial failure semantics ('One bad item never blocks the others'), and response reporting exactly which succeeded/failed. This gives the agent realistic expectations about outcomes.
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?
A single dense paragraph that front-loads the core purpose and usage. It is efficient, but the phrase 'everything firestarter_list accepts per-item is accepted here too' is slightly verbose and could be tightened. Overall well-structured and scannable.
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 bulk-write tool with a complex schema and no output schema, the description is remarkably complete: it covers required fields, batch limits, partial failure behavior, and directs to the single-item alternative. An agent can call this correctly without additional 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?
Schema coverage is 100% for the single `products` parameter. The description adds meaning beyond schema by highlighting which fields are required per item (product_name, base_price), that it accepts all fields from firestarter_list, and the 100-item limit. This enriches the schema without redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Create) and resource (MANY products at once), explicitly distinguishes from the single-product sibling firestarter_list and clarifies bulk migration use case. An agent understands exactly what the tool does and how it differs from alternatives.
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 (migrating existing catalog from CSV/spreadsheet) and when-not (for a SINGLE product, use firestarter_list instead, which has richer per-listing guidance). Also specifies batching for >100 products. This fully routes the agent to correct tool 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?
Annotations declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description reinforces this with 'Read-only: never charges or changes anything' and adds substantial context beyond the annotations: the meaning of the buyable flag, result ordering ('buyable, cheapest first'), environment behavior ('test/live follows the API key's environment'), and pagination behavior ('when more exist the result notes it'). This fully informs an agent about side effects, result semantics, and edge cases.
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 long but densely packed — every sentence contributes distinct information: purpose, differentiation, result contents, buyable semantics, ordering, country filtering, environment, limits, and read-only safety. It is well-organized and front-loaded, but the length is at the upper edge for a tool description, so it doesn't achieve perfect conciseness.
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's complexity (7 optional parameters, result semantics, environment behavior, and a sibling with overlapping scope), the description is fully complete. It tells agents what results contain, how to interpret buyable vs browse-only, how ordering works, what to do when more results exist, and that the operation is side-effect-free. An agent can invoke this tool correctly without any additional external knowledge.
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 100%, so the schema already documents all 7 parameters. The description goes further by giving practical search-quality advice for query ('matches best on real product nouns'), explaining what does NOT belong in query ('price constraints belong in max_price'), and revealing hidden behavior ('price phrases that do slip into the query are auto-extracted into the price filters'). This adds real value beyond the schema, though a bit more per-parameter detail could push it to 5.
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: 'Search the Firestarter NETWORK catalog — products listed for sale by ALL sellers — without starting a purchase.' It also names the buyer-facing role and distinguishes itself from firestarter_listings, making the tool's scope immediately 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 this tool ('buyer-facing browse tool,' 'see what's available before buying, compare prices, or check whether the network carries an item') and directly names the alternative it is not: 'Different from firestarter_listings, which only shows YOUR OWN seller listings.' It also tells agents how to chain the resulting listing_id into firestarter_execute, providing clear workflow 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?
Despite annotations indicating destructiveHint=true, the description adds crucial behavioral details: the seller funds the discount, the platform fee is charged on discounted total, rejection conditions for low-priced orders, and the need for explicit confirmation on deep discounts. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed but well-organized, front-loading the purpose and then covering key constraints and special cases. It is not overly verbose given the complexity, though a few sentences could be tightened without losing 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?
For a tool with 12 parameters and no output schema, the description covers essential context: prerequisites, funding implications, edge cases (deep discount, minimum order), and rejection scenarios. It provides enough for an agent to correctly invoke the tool in a variety of situations.
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 all 12 parameters with descriptions (100% coverage), so baseline is 3. The description adds extra context about discount types (percentage, fixed amount, free shipping) and natural-language date parsing, going slightly beyond schema but not duplicating it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create), the resource (voucher/coupon/promo code), and its purpose (applied to listings). It distinguishes from sibling tools like update_voucher and set_market_tiers, and specifies the discount types.
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 the prerequisite (SELLER account with at least one listing) and contrasts with the case of community-market owners who should use set_market_tiers. It also covers when deep discount confirmation is needed and mentions the alternative of targeting a specific listing.
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 (destructiveHint, idempotentHint), the description explains that the change is not retroactive (existing orders keep their frozen margin), that zero disables the margin, and that there is a transaction ceiling. This tells the agent what side effects to expect and what is not affected.
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 dense but front-loaded with the core verb and noun, and every following clause adds a distinct fact (prospective effect, zero-off, ceiling, sibling distinction). It could be split into shorter sentences but is still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a single parameter and annotations already conveying read/write/destructive/idempotent traits, this description covers the practical edge cases: future-only application, turning off with 0, the 10%/$50 ceiling, and the distinction from market share_bps. Nothing essential is missing 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?
Although the schema already documents margin_percent fully (0–10, conversion to bps), the description adds operational meaning: it is a markup on the item total, only for purchases through the org's own API keys, and subject to a platform ceiling. This enriches the bare schema definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb 'Set or change' and a precise resource 'developer margin', defines what that margin is, and explicitly contrasts itself with firestarter_create_market's share_bps. No ambiguity about what action is performed.
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?
Gives condition-based guidance: the margin applies to future purchases only, 0 turns it off, and it is explicitly contrasted with a different concept (share_bps in firestarter_create_market), steering the agent away from the wrong sibling. The examples clarify when a user would request this.
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 only signal that this is a mutating, non-destructive tool; the description adds substantial behavioral context beyond that: draft activation requires a positive price and photo, high-value/luxury drafts require a possession-verification photo with an FS-XXXX code flow, and activation returns instructions. It also clarifies that pricing changes belong on a different tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but dense, and the core purpose is front-loaded before edge cases and routing notes. The second use-case sentence is slightly redundant with the opening field list, but each behavioral caveat (draft activation, high-value verification, reprice routing) 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?
For a 23-parameter mutation tool with no output schema, the description covers the important activation workflow, prerequisites, verification handoff, and alternative-tool routing. The schema fully documents the parameters, so nothing needed to invoke the tool correctly appears to be 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?
Schema coverage is 100%, so the baseline is 3; the description adds value by explaining that status='active' on imported drafts triggers activation requirements and by mapping field names like 'dispatch time' to their conceptual purpose. It doesn't need to duplicate schema detail, but the activation semantics for 'status' go beyond the schema's bare 'New listing status'.
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 starts with a specific verb and resource — 'Update a listing's product details' — and enumerates the exact fields it can modify. It also explicitly distinguishes itself from firestarter_reprice and firestarter_verify, so an agent can tell this tool apart from related siblings without opening schemas.
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 gives concrete when-to-use scenarios: rename, change description, update stock, pause/reactivate, fill/correct fields, and activate imported drafts. It also names exclusions — pricing changes go to firestarter_reprice and verification photos go to firestarter_verify — leaving little to inference.
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 annotations only indicate readOnlyHint: false and destructiveHint: false. The description adds rich behavioral context: the FS-XXXX code written by hand, the two-state outcome (match vs. mismatch), the fact that unreadable photos are held for review rather than rejected, and the follow-up activation step. This gives the agent a clear mental model of the tool's side effects and state transitions beyond what structured fields declare.
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 dense but not padded - it front-loads the core action, then the trigger conditions, then walks efficiently through the workflow and outcomes. The parenthetical trigger list is concise, and the three-state outcome paragraph is economical. The only slight inefficiency is that 'photographs the paper next to the item, and sends the photo in chat' contains slightly more narrative color than strictly necessary, but it does clarify the expected photo composition.
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 tool acting as a checkpoint in a multi-step flow, the description covers everything an agent needs to call it correctly: the trigger conditions, the exact required format (handwritten code, photo content), the follow-up action (activate via firestarter_update_listing), and the full range of outcomes including the edge case of an unreadable photo. With no output schema required, the description does not overhang its bounds.
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% - both listing_id and photo_url have useful descriptions. The description adds some narrative context that connects the parameters ('sends the photo in chat - pass that photo's URL here with the listing ID') and provides the FS-XXXX format detail for the code. The description reinforces the parameter relationship but doesn't need to be heavily relied upon for parameter understanding; the schema already carries that weight effectively.
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 pairing ('Submit a possession-verification photo for a listing whose activation asked for one') and immediately scopes the tool with concrete trigger conditions (high-value >= $500, luxury category, source-URL conflict). The purpose is unambiguous and easily distinguished from siblings like firestarter_update_listing or firestarter_upload_image, which handle different steps in the workflow.
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 this tool applies (activation asked for a photo) and names a sibling (firestarter_update_listing) for the follow-up step ('then activate via firestarter_update_listing'). It also clarifies what content the photo must contain (handwritten FS-XXXX code next to the item) and the three possible outcomes (instant match, flagged mismatch for resubmission, held for review), leaving almost no ambiguity about when to invoke this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses that access tokens are secret, stored encrypted server-side, and never echoed in responses. It also discloses the current auth limitation (access token, not one-click OAuth) and the idempotent behavior when a TikTok Shop is already connected. This is valuable behavioral context the annotations do not 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 somewhat long but every sentence carries necessary information: purpose, behavior modes, auth requirements, the trigger use case, and security handling. The most important facts (what it does and how to invoke it) are 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?
Given that there is no output schema, the description adequately explains what the agent can expect: connection creation, status returns for existing connections, and setup instructions on the no-argument call. Security-sensitive handling is also covered, making this complete enough for an agent to both select and invoke the tool confidently.
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 100%, so the schema already documents both parameters. The description adds important extra semantics: that access_token is a secret credential, that shop_domain and access_token are required together to create, and that omitting access_token switches the tool into status/instruction mode. This goes beyond what the schema states.
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: 'Connect a seller's TikTok Shop to Firestarter so their catalog syncs and orders flow back.' It clearly distinguishes this tool from platform-specific siblings like firestarter_connect_shopify by naming TikTok Shop explicitly and by describing the dual create/status 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 gives explicit when-to-use guidance: 'Use this whenever a seller mentions TikTok Shop or wants to sync their TikTok products.' It also explains the two call modes — no arguments for status/setup, access_token plus shop_domain to create — so an agent knows exactly which invocation fits the situation.
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 openWorldHint=true and readOnlyHint=false, annotations confirm mutating behavior. The description adds crucial details that annotations don't: it creates an attribution program, requires a `share_bps` that may be capped with effective value returned, and clarifies that payouts are only needed later—all enhancing the agent's understanding of side effects and prerequisites.
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 information-dense but remains readable. It front-loads the most important info about usage context and prerequisites, followed by parameter semantics and related tools. It's long but every sentence adds value to the agent's call decision.
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 tool with 5 parameters and no output schema, this description covers all necessary aspects: what it creates, what's required, what fails the call, what happens later, and how to perform follow-up actions. The absence of an output schema is compensated by explaining the response contains the effective `share_bps` value.
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?
Although the schema already has excellent parameter documentation, the description adds critical context for `handle` (case-insensitivity, uniqueness, failure behavior) and `share_bps` (platform-fee basis points, capping). This complements the schema without redundancy.
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 up a community/affiliate market'), identifies the resource, and clearly differentiates from siblings by explaining the relationship to seller onboarding and payouts. It mentions alternative tools (firestarter_set_market_handle, firestarter_market_link) to avoid ambiguity.
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 when to use the tool, and lists related tools (firestarter_set_market_handle, firestarter_market_link) and even alternative future actions like deferring handle selection. It also clarifies non-requirements (no seller account, no Stripe, any country), preventing common misuses.
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 only convey readOnlyHint=false, openWorldHint=true, and destructiveHint=false. The description adds crucial behavioral context beyond those: the tool stages options for approval without charging, browse-only options cannot be approved, auto_pay requires explicit prior authorization, a saved address is silently reused, and test-mode hold flags have specific sandbox 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the most important facts — Step 1, no payment yet, and the full flow — and is organized in a logical progression from purchase flow to shipping, addresses, localization, listing pinning, and special modes. It is long, but the complexity of the tool and absence of an output schema justify most of the length; a small amount of overlap with parameter descriptions keeps it from a perfect score.
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 carries the full burden of explaining what the agent should expect, and it does so thoroughly: ranked options, delivery options, masked default_delivery, needs_more fields, browse-only options, and the buy-flow sequence. It also covers edge cases like no saved address, wrong-country results, listing_id pinning, auto_pay pre-authorization, and test-only hold flags, making it highly complete for an agent selecting and invoking this tool.
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?
Although schema coverage is 100%, the description meaningfully extends the schema: it explains that `request` alone is sufficient and can be refined later, that `location` should be passed whenever known for localized results, that `listing_id` should always be passed when available, and that `voucher_code` is only for private or targeted codes. It also clarifies delivery_address shape trade-offs and test-mode hold behavior beyond the raw schema text.
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 'Start a purchase. Step 1 of the buy flow' and precisely defines what the tool does: find matching products, verify the seller, compute pricing and shipping, and return ranked options awaiting approval — while explicitly stating it does NOT pay yet. It also names the full flow and contrasting sibling tools, so there is no ambiguity against firestarter_approve, firestarter_receipt, or firestarter_track_order.
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: this is the first step of purchasing, while approval/payment belongs to firestarter_approve, proof to firestarter_receipt, and tracking to firestarter_track_order. It also clarifies that shipping quoting and comparison happen via firestarter_shipping_options/firestarter_shipping_estimate before a purchase starts, and that no card is needed until after approval.
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 annotations only declare idempotent and destructive hints, while the description adds substantial behavioral context: earnings wait in escrow and selling pauses only under dynamic thresholds, Stripe locks the country permanently and a wrong one requires discarding the account, provider reach is explicitly uncertain, and unsupported countries produce a clear 422. This far exceeds what the annotations convey.
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 long but front-loaded with the core distinction and each major topic—status check, setup, thresholds, provider reach, country lock, eligibility routing—earns its place. It loses a point for density and mild redundancy, such as "no client-side ineligible-country list" appearing alongside "do not pre-filter on the seller's behalf," which say similar things in one unbroken block.
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 the absence of an output schema, the description provides almost everything an agent needs to invoke the tool correctly: how to check status, how to set up a method, provider-specific parameter requirements, error behavior, permanent country-lock consequences, and the right sibling tool for eligibility checks. No meaningful invocation context is missing.
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?
Although schema coverage is 100%, the description adds meaning beyond the schema: country is only required for Stripe unless already recorded at registration, the API refuses to guess because Stripe locks the country permanently, country is irrelevant for PayPal, omitting provider means status check, and there is no client-side ineligible-country list. These details materially change how an agent should fill 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 uses a specific verb and resource: "Manage seller payout method," and immediately disambiguates scope: "this is how a seller RECEIVES money, not permission to sell." It distinguishes the no-argument status mode from the provider setup mode and even routes country-specific checks to firestarter_payout_eligibility, so it is clearly separated from siblings like firestarter_payment_method and firestarter_connect_payouts.
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 when to call the tool: "Call with no arguments to check current status. Pass `provider` to set up a new method." It also gives an exclusion rule—"Do not promise either rail for a country without checking"—and names the alternative tool, firestarter_payout_eligibility, for pre-checking a country. This leaves little to inference.
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 are minimal (readOnlyHint=false, openWorldHint=true, destructiveHint=false), so the description carries the behavioral burden. It goes beyond annotations by revealing that the tool creates an escrow invite (a side effect) without directly contacting the seller—the buyer must manually send the message. It also discloses that the fetch may be blocked on certain platforms, and that providing title/price yields a usable invite even on fetch failure. This is critical 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but effective: it packs a lot of critical context (buyer-side, manual messaging, fetch block, parameters) into a few sentences. It is front-loaded with the primary purpose and proceeds to key usage details. Slightly long, but every sentence contributes essential 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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex (external integration, seller invite, notification), but the description covers the workflow, failure modes, and parameter usage. It explains the seller claim link, where notifications go, and the fallback for blocked fetches. With no output schema, it doesn't describe return values, but the return is likely minimal (invite link), and the description provides enough for an agent to act. No major gaps.
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?
Schema coverage is 100%, so parameters are well-defined in the schema. The description adds value beyond the schema by clarifying the role of buyer_email (where the goes-live notification lands), explaining that title and price are buyer-supplied to compensate for blocked fetches, and indicating that source_url is the external listing URL. It also states that buyer_name is shown to the seller on the claim page, which the schema does not mention.
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 buyer-side purpose: to pay for an external listing via Firestarter escrow. It specifies the action (create an escrow invite) and the resource (the listing), and distinguishes it from other firestarter_ tools by its invocation context (found a listing on another site). The mention of 'Firestarter never contacts external sellers' and the seller claim link makes 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?
The description explicitly says when to use this tool (buyer found a listing on an external marketplace and wants escrow) and implies when not to (when not buying from an external site). It also provides crucial guidance on the requirement to send the message manually, handling of blocked fetches for specific platforms, and the need for buyer email and listing URL. This guides the agent on required fields and fallback behavior.
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 destructiveHint annotations, the description discloses that no execution, approval, or purchase occurs, that the returned rows are informational and not an approval menu, that street-less destinations may get estimate tiers, and that exact rates are re-quoted at approval. This significantly enriches the annotation-only picture.
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 dense and front-loaded with purpose and read-only status. It is longer than strictly necessary, but every sentence contributes operational guidance about inputs, outputs, or routing.
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 estimate tool with no output schema, the description covers inputs, return contents, caveats, and related tools. Nothing essential is missing 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.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds important selection logic: prefer address_id, use country+ZIP or city as fallback, no street address needed, and listing_id sources (preview, catalog, listings, share link). It also clarifies output meaning in the context of 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?
States a specific verb and resource: estimate shipping for a listing before purchase. Explicitly differentiates from firestarter_execute and firestarter_shipping_options by clarifying this is informational and not an approval or purchase path.
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 when to use it: while the buyer is browsing, to answer 'how much is shipping?' or 'can this ship to me?'. Also gives exclusions and alternatives, directing actual purchase to firestarter_execute and post-order shipping to firestarter_shipping_options.
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 explicitly states that revocation does not affect existing live drops and that they continue until expiry or exhaustion. It clearly communicates the non-cancellation behavior, which is crucial for a revocation action. This content is not available in annotations or structured data, and it substantially clarifies the tool's actual effect.
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, each carrying essential information: the reciprocal action and the non-cancellation caveat. Front-loaded with a clear verb and object, with no filler. All sentences earn their 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?
The description fully covers the tool's purpose, its relation to sibling tools, the parameter's meaning, and the critical behavioral caveat about existing drops. Since there is no output schema, the description does not need to explain return values, and no essential information is missing 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?
The schema documents program_id with a description, achieving 100% coverage. The description adds semantic context by referring to it as 'this community/market program id', but because schema coverage is complete, the description's added value is small yet meaningful. This justifies slightly above the baseline of 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?
Describes a specific reciprocal action ('Revoke a standing approval you granted with firestarter_trust_community_drops') and identifies the resource affected (a community's NEW drop requests). It clearly distinguishes this from the trust/approval tools and explains the practical consequence of revocation.
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 this tool applies (when you previously granted a standing approval and want to revoke it) and what to expect afterward (requests revert to manual approval via firestarter_approve_drop / firestarter_reject_drop). This provides direct routing among sibling tools and effectively discourages misuse for canceling existing drops.
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 only indicate that this is not read-only and not destructive, so the description carries the behavioral burden. It does so well by explaining server-side fetching and re-hosting, the 6 MB limit, the return of a permanent URL, and the known failure mode of download-and-rebase.
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 dense but every sentence earns its place: purpose and output, input-form alternates, decision rule, and failure mode. It is front-loaded with the most important information and contains 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 tool with no output schema, the description supplies the needed expectation of the returned hosted URL, input requirements, constraints, and a known pitfall. That is sufficient for an agent to invoke it and interpret 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?
The schema already covers all three parameters at 100% coverage, so the baseline is 3. The description adds value beyond the schema by framing image_url as the preferred form, image_base64 as the fallback, and explaining the real-world tradeoff, which helps the agent decide between them 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 opening sentence states a specific verb and resource ('upload a product photo') and the concrete outcome ('get back a permanent public URL'). It also identifies downstream consumers (firestarter_list and firestarter_update_listing), which clearly distinguishes this tool's role among the many firestarter siblings.
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 when to use image_url versus image_base64: use image_url whenever a URL exists, and fall back to image_base64 only when no URL exists. It even explains why image_url is the reliable form by naming the known failure mode it avoids.
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 important behavioral details beyond annotations: the result is a non-live draft, fetches are attempted but often blocked, specific error codes (PLATFORM_BLOCKED, EXTRACTION_EMPTY) are documented, and activation conditions are stated. This significantly exceeds what readOnlyHint=false and destructiveHint=false convey.
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 long but every sentence carries operational value. It front-loads the core purpose and draft outcome, then methodically covers fetch behavior, failure recovery, and activation requirements 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?
For a tool with no output schema and three interrelated optional parameters, the description covers the full workflow: input modes, platform-specific behavior, error handling, retry guidance, and downstream activation prerequisites. Nothing needed for correct invocation is left unexplained.
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?
Despite 100% schema coverage, the description adds real semantic value: it explains the strategic relationship between source_url, raw_text, and photo_urls, identifies known-blocking platforms, and clarifies when each parameter is required or should be sent preemptively. This goes well beyond the schema's individual parameter descriptions.
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 ('Import'), the resource ('a seller's EXISTING listing from another marketplace'), and the concrete outcome ('creates a DRAFT listing'). It clearly distinguishes itself from listing-creation siblings by emphasizing EXISTING listings and the draft status.
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 explains exactly when to use it (importing from Craigslist, Gumtree, own site) and how to handle blocked platforms by pairing source_url with raw_text and photo_urls. It also names alternatives for follow-up actions (firestarter_update_listing, firestarter_reprice), giving explicit when-to-use context.
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 only provide readOnlyHint=false and destructiveHint=false, so the description carries the burden of behavioral detail. It does this thoroughly by explaining how 'replace' becomes the exact shelf in order, what 'add' and 'remove' do, and that own listings are rejected. It also states the 15-pick limit and the visible note, giving a clear picture of side effects on the shelf.
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 long but densely informative: it front-loads the core purpose, then covers the actions, constraints, and related tools without repetition. Every sentence earns its place, and the structure helps an agent quickly extract the essential behavior.
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 rich input schema and an output schema, this description still covers all situational gaps: ownership requirement, source of listing IDs, behavior of each action, ordering semantics, tier gating, and the key 'own listings are rejected' rule. The agent can invoke it correctly with this single description.
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?
Schema coverage is 100%, so the baseline is 3, but the description goes far beyond structured fields. It clarifies the meaning of 'replace' (exact shelf and order), 'remove' (only listing_id used), the 'min_tier' mechanic ('members get first look at new picks'), and the 'note' purpose. This adds genuine operational insight above what the JSON Schema states.
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 and target resource: curate the 'Recommends' shelf for a community market the agent/owner has access to. It also clearly distinguishes picks as other sellers' listings and says own listings are rejected, making the purpose precise and easily differentiated from sibling market tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells the agent when to use the tool: 'Use when an owner wants to add, remove, reorder, or replace what their community recommends.' It also provides exclusions ('your OWN listings... are rejected here') and even points to a related tool for tier setup (firestarter_set_market_tiers), which helps route the agent.
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:

[![firestarter-mcp MCP server](https://glama.ai/mcp/servers/Analog-Labs/firestarter-mcp/badges/card.svg)](https://glama.ai/mcp/servers/Analog-Labs/firestarter-mcp)

Score Badge

Copy to your README.md:

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

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