KnownFix

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

The description discloses that the tool both previews and redeems the paid report, implying a side effect on the second call when payment parameters are supplied. It also clarifies that the first call is free. This goes beyond the annotations, which only indicate non-read-only and non-idempotent behavior, and does not contradict them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured: first the core function, then the step-by-step usage flow. Every sentence adds necessary guidance, and the key workflow detail is front-loaded before the paid-report instructions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with a payment flow and multi-step redeeming behavior, the description covers all necessary context: free vs. paid usage, prerequisite calls, payment parameters, and the fact that delivery is built in. The presence of an output schema covers return values, so nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

While the schema already describes each parameter, the tool description adds the meaningful workflow context: how `paymentOffer` is obtained from `get_offer`, why `paymentTx` is required, and how these parameters combine on the second call. This is essential semantic information an agent needs to use the parameters correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Readiness audit of any agent-facing URL', and enumerates concrete checks (MCP handshake, CORS, discovery docs, payment-offer behaviour). This distinguishes it from sibling audit/check tools and leaves no ambiguity about scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly explains when to call with only `url` for the free grade vs. calling after `get_offer` and payment for the full report. It also names the prerequisite tool (`get_offer`), the required payment step, and notes that no separate delivery tool is needed, providing a complete usage workflow.

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

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

Annotations already mark the tool as read-only, idempotent, open-world, and non-destructive, but the description adds valuable behavioral context: it fetches the page, never modifies it, analyzes inline style CSS, only counts external stylesheets without fetching them, and rejects certain target types. This goes beyond what annotations provide and clarifies the tool's actual runtime behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences with no wasted words: it front-loads the core action, details the checks and fetch behavior, and closes with a sibling-tool pointer. Every sentence contributes to correct tool selection and use.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With one well-documented parameter, rich annotations, an output schema, explicit target restrictions, and a clear sibling alternative, the description fully covers what an agent needs to invoke the tool correctly. There are no significant missing details about side effects, scope, or selection.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the schema's url parameter already explains the target restrictions and CSS analysis behavior. The description reinforces the same points but adds little new semantic detail beyond the schema, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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: 'Run a read-only theme audit on a public HTTP(S) page.' It then enumerates concrete audit checks such as brace errors, token gaps, incomplete dark themes, missing body backgrounds, and WCAG body-text contrast, making the tool's function unambiguous and distinct from its siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly states when to use this tool versus audit_endpoint: 'Use audit_endpoint instead for MCP, CORS, discovery, and payment readiness.' It also implies the appropriate use case (theme/contrast/CSS auditing) and notes URL restrictions, giving an agent enough context to select between alternatives.

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

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

The description goes beyond the annotations by disclosing that the call may atomically consume the ticket's one-time delivery and instructs the agent to save the returned body. It also notes the ticket can be redeemed only once, which is critical behavioral context not captured by annotations alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three dense, purposeful sentences with no filler. The key warning about consuming the ticket is front-loaded, and the sibling alternative is placed at the end. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists and the single parameter is fully documented, the description covers everything an agent needs: what to pass, what to expect, the side-effect risk, and how to choose between this and get_fix. No important context is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already covers the single parameter fully, so the baseline is 3. The description adds extra meaning beyond the schema by explaining the ticket's origin (from request_fix), its one-time nature, and the need to reuse it unchanged and never publish it. This is meaningful supplementary guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Check') and resource ('a private ticket from request_fix'), and clearly enumerates the possible return values, including pending, declined, not-eligible, redeemed, or the full fix. It also differentiates itself from get_fix by naming when that sibling should be used instead.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly tells the agent when to use this tool: with a private ticket from request_fix. It also gives an alternative, 'Use get_fix when you already have a catalog id,' and warns not to create another request while this ticket is pending. This leaves no ambiguity about tool selection.

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

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

Annotations mark this as non-read-only and non-idempotent, and the description aligns by revealing that payment confirmation is atomic, targets exactly one matching Base payment, and transitions the order into review. It also discloses the privacy requirement for ticket and signed offer, adding useful context beyond the minimal annotation set.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences cover mode selection, state transition, return behavior, and security guidance with no filler. Critical usage conditions are front-loaded, and every clause adds distinct information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the main modes, the state-changing effect, return outcomes, and privacy expectations. It is slightly ambiguous about what happens when only one of paymentTx or paymentOffer is provided, since the described alternatives are 'with both' and 'without payment fields', but this is a minor edge case for an otherwise strong definition.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so the baseline is 3. The description adds meaning by explaining the combined effect of paymentTx and paymentOffer, the 'exactly one matching' constraint, and the resulting review state, which is not fully captured by individual parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Check a private service order by its svc_ ticket') and clearly differentiates two behaviors: confirming payment and retrieving status/report. It distinguishes this tool from siblings like check_request and check_submission by focusing on service orders and the svc_ ticket.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly explains when to include paymentTx and paymentOffer (to confirm and move to review) and when to omit them (to fetch status/report). It also gives lifecycle guidance with 'once complete', making invocation conditions unambiguous.

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

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

Beyond the readOnly/idempotent/destructive annotations, the description discloses that the tool returns only a limited set of states, never returns submitted text or contributor details, and has no side effects. This is valuable behavioral context the annotations alone 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three dense sentences cover purpose, return scope, privacy guarantees, side effects, and routing alternatives. Every sentence contributes useful information, and the most important usage constraint is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a single documented parameter, rich annotations, and an output schema, the description fully covers the operational behavior, privacy constraints, and successor tool guidance. Nothing essential is missing for an agent to select and invoke this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already fully documents submissionId with details about it being a private UUID, returned once by submit_fix, and not usable to retrieve submitted text. The description's reference to 'private submissionId returned by submit_fix' adds no meaning beyond the schema, so the baseline for high schema coverage applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Check') and names the exact resource (a private submissionId from submit_fix). It clearly distinguishes this tool from siblings by focusing on review states rather than catalog retrieval, and even names get_fix as the downstream tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when to use the tool (after submit_fix returns a submissionId), when to switch to get_fix (once cataloged), and what not to do (resubmit merely because review is pending). This gives an agent clear routing guidance.

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

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

Annotations indicate a non-read-only, non-idempotent operation, and the description adds useful behavioral detail: free samples return immediately, paid fixes involve a diagnosis preview plus pay-and-redeem action, and users must not pay again if a proof is pending or denied. 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but front-loaded with the main purpose, followed by the free/paid flow and a safety warning. Every sentence carries necessary information, though the paid-fix sentence is long and could benefit from bullet formatting.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of a two-step paid flow, the description covers the required call sequence, parameter usage, security note about the private token, and the free-sample case. An output schema exists so return values do not need elaboration, and no critical invocation detail appears missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the schema already describes each parameter, including origins and when to omit payment fields. The description reinforces sequencing but does not add substantial semantic meaning beyond what the input schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description states the specific action 'Get or redeem a fix' and the resource (a fix identified via search_fixes or list_catalog). It clearly distinguishes this tool from search/list siblings and clarifies the two-step paid redemption flow.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit context: fixes come from search_fixes or list_catalog, free samples return immediately, and paid fixes require an initial id-only call followed by a second call with paymentTx and paymentOffer. It does not explicitly state when to prefer an alternative like get_offer, but the flow is clearly scoped.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world behavior. The description adds useful context beyond that: no account, payment, paid body, or private data is involved, and it supports clients unable to read MCP resources. Rate limits or auth specifics are not mentioned, but the annotations carry 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded, starting with what is returned and following with constraints, alternatives, and client compatibility. Every sentence adds selection or behavioral value, with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that an output schema exists and annotations cover safety, the description provides everything else an agent needs: the free-workflow scope, the get_overview prerequisite, the premium alternative, and the client-resource limitation. No material invocation detail is missing for a simple one-parameter read tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explicitly define the required id parameter. However, it does link the id semantically to a workflow 'listed by get_overview,' which helps an agent understand where valid identifiers come from. The enum itself supplies the exact allowed values, so this is minimally adequate rather than rich.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Return the complete Markdown body of one free workflow.' It also distinguishes this tool from premium-product siblings by naming list_skills/get_skill as the alternative, so an agent can select it without opening another schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear usage conditions: the workflow must be listed by get_overview, and premium products should use list_skills/get_skill instead. It also adds the special case of clients that cannot read MCP resources, leaving no ambiguity about when this tool is appropriate.

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

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

The description goes beyond the readOnly/idempotent annotations by disclosing the one-hour validity, bearer nature, and that no-arg calls return the general settlement document. The verb 'create' is slightly ambiguous with readOnlyHint, but the 'returns' language frames it as generating an ephemeral signed document rather than a persisted resource.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, no filler. The central behavior and expiry are front-loaded, the exclusion rule follows, and currency/no-arg behavior closes with practical detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and annotations already covering safety/idempotence, the description supplies the key decision-relevant context: when not to call, what no-args does, and what currency means. Nothing essential for correct invocation is left unspecified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already describes the parameters. The description adds practical meaning: 'USDC for Base Pay or ETH for exact wei', the no-product argument variant, and confirmation of which product types map to which catalog shelves.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific action ('Create or refresh') and a concrete resource ('one-hour signed bearer offer'), and scopes it to skill, bundle, audit, or fix. This makes it easy to tell apart from sibling tools such as get_fix/get_skill, which return catalog content rather than payment instruments.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when not to call the tool ('Do not call this after a paid search_fixes result or an unpaid get_fix/get_skill result') and why (those responses already include payment rails). It also gives selection guidance for currency and defines the no-argument fallback.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered structurally. The description adds real value beyond them by stating there is no account, payment, signed offer or order creation, clarifying the side-effect-free and cost-free nature of the call.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core purpose and the negative boundary before the routing advice; no sentence is wasted. The first sentence is a dense enumerated list, which slightly slows reading but every item conveys scope.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With zero parameters and an output schema present, the description need not explain return values. It covers scope, boundaries and sibling routing, leaving nothing an agent needs in order to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so per the rubric the baseline is 4; there is nothing for the description to disambiguate. The description does not need to explain arguments and correctly does not attempt to.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('One free overview of all KnownFix offerings') and enumerates its contents, so an agent knows it is a discovery/index tool rather than an action tool. It differentiates itself from search_fixes and list_services by routing to them, but does not clearly distinguish its scope from siblings like list_catalog, list_skills or get_offer.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit routing: 'Use search_fixes first for an exact error; list_services for full engagement terms,' and states the negative boundary ('No account, payment, signed offer or order creation'). The agent knows both when to call this tool and when to prefer a sibling.

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

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

The description clearly discloses the two-phase redemption behavior, what the first call returns, what the follow-up call requires, and the need to keep the private paymentOffer confidential. This adds substantial behavioral context beyond the annotations' readOnlyHint=false and idempotentHint=false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four dense sentences cover purpose, usage flow, exclusions, and a payment-safety warning without repetition or filler. The most important scoping information is front-loaded, and every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a paid redemption flow with an output schema, the description covers prerequisites, the exact two-step call sequence, expected outputs before and after payment, alternative routing to get_fix, and a crucial financial caution. Nothing needed to invoke the tool correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining the temporal relationship between parameters: id alone first, then matching paymentTx and paymentOffer after payment. This helps an agent understand how to sequence the parameters in practice.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific action ('Get or redeem a premium skill or multi-fix bundle') and a clear prerequisite ('after choosing with list_skills'). It explicitly contrasts itself with get_fix, making the tool's scope unambiguous and distinguishing it from a similarly named sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: after list_skills, with the two-phase call pattern. It also provides a direct when-not-to-use rule ('Do not use this for individual fixes; call get_fix instead') and a safety warning about not paying again when a proof is pending or denied.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds behavioral context by stating the tool does not rank or create offers, and specifies the exact fields returned, which is beyond annotation data. 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core action and content, followed by a concise alternative routing. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with no parameters, an output schema, and annotations covering safety, the description fully equips an agent to decide when and how to call it. The only potential missing detail (pagination) is not required given the tool's nature.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With zero parameters, the schema carries no burden and the description correctly adds no parameter details. The baseline for 0-param tools is 4, and no compensation is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Browse') and a clear resource (the fix catalog), lists the fields it returns (signature, title, tag, confidence label, free-sample flag), and explicitly contrasts with search_fixes. This clearly distinguishes it from sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit routing: 'Use search_fixes instead when diagnosing a specific error' — names the alternative and the condition that selects it. No ambiguity.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds useful behavioral context: it returns privacy-safe tracked links, depends on Fourthwall for live pricing and availability, and does not place an order or collect checkout data. 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences with the action and resource front-loaded, followed by relevant output and boundary details. Every sentence adds value without redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no parameters, a complete output schema, and annotations covering safety, the description provides all necessary context. It communicates what an agent can expect in the response and explicitly rules out transactional behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema coverage is effectively 100%. The description appropriately focuses on output behavior rather than parameter details, which matches the baseline for parameterless tools.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Browse the KnownFix Merch Store' and returns fixed product ids, lines, formats, and tracked links. The Fourthwall storefront reference clearly distinguishes it from siblings like list_catalog, list_services, and list_skills.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies a browsing use case and explicitly excludes order placement and checkout data collection, which tells an agent when not to use it. However, it does not name alternative tools or provide direct conditions for choosing this tool over list_catalog or other listing siblings.

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

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

Annotations already declare a safe read (readOnly, idempotent, non-destructive), and the description adds real beyond-annotation context: the manual-service routing rule, the SaaS-security written-authorization requirement, and the operator approval gate. Return contents are also described, which is extra since an output schema exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with what gets compared and what comes back; the later sentences carry routing and authorization constraints that earn their place. It is dense and mixes return-value detail with policy rules, costing a little readability, but no sentence is pure filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With rich annotations, a present output schema, and zero input parameters, the description only needs to cover routing and prerequisites, and it does both (order-page vs order_service, written authorization, spending approval). An agent can act on it without further context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. Schema coverage is 100% and no input semantics are missing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States the comparison verb and enumerates the actual offerings (KnownFix reviews, Verified Repo Fix, Microsite Launch), which is more concrete than the bare title 'List professional services'. It also implicitly separates itself from order_service, though it never says plainly 'all available services' and the phrasing 'Compare all current...' is slightly oblique.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: manual services must use their own order page, 'not order_service', and checkout-only services require operator spending approval and target authorization. It does not distinguish this tool from other listing siblings (list_catalog, list_skills, list_merch, get_offer), so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, but the description adds meaningful behavioral context beyond them: full bodies are paid, while free outlines, provenance, formats, and exact prices are returned. It clarifies the paywall boundary and the data shape without contradicting any annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences carry the full message: what the tool does, what it returns, and which sibling to call next. The most important purpose information is front-loaded, and no sentence is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-parameter read-only listing tool with an output schema, the description is complete: it states return contents, the paid/free split, and follow-up actions. The annotations cover safety and idempotency, so nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

This tool has zero parameters, so the schema trivially covers 100% and there is no parameter burden for the description to carry. Per the baseline for 0-param tools, a 4 is appropriate; the description correctly avoids inventing parameter details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description opens with a specific action and resource: 'Compare premium skills and multi-fix bundles.' It then lists concrete outputs (ids, free outlines, provenance, formats, exact prices), making the tool's function unmistakable. It also names related sibling tools get_skill and search_fixes, so an agent can 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly routes the agent to the correct next tool: 'Call get_skill with a chosen id for signed USDC and ETH checkout; use search_fixes for a single error.' This gives clear when-to-use direction and names alternatives, satisfying the highest bar for usage guidance.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the mutation profile is covered; the description adds meaningful context on spending approval, target eligibility, and ticket confidentiality. The gap is that the payment mechanics of the signed checkout (capture timing, refunds, duplicate-order risk given idempotentHint=false) are not described.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then eligibility exclusions, then required confirmations and the privacy instruction. Four dense sentences, no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need no explanation, and the description covers eligibility, exclusions, approval, and confidentiality well. It stops short of describing what the caller should do after receiving the ticket or how repeated calls behave, which matters for a non-idempotent ordering tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 80%, and the description adds real meaning beyond the schema: targetUrl must be an authorized public HTTPS target, notes must not contain confidential data, and the enum's requiresScopeApproval members are carved out as ineligible. It does not add syntax detail for publishTarget, which is minor given the schema describes it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific compound action: creating a private ticket plus a signed Base USDC/ETH checkout, scoped to eligible automated services. The verb+resource is unambiguous and unlike sibling read/listing tools such as list_services or check_service_order.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when NOT to call it — services with requiresScopeApproval (SaaS security, Microsite Launch) and paymentTiming:after-verified-delivery (Verified Repo Fix) — and routes those to their published manual-approval page. It also states the preconditions (authorized public HTTPS target, operator spending approval).

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

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

The description adds meaningful behavioral context beyond annotations: it discloses a one-blocker-per-offer cardinality limit ('at most one aggregate count is accepted per offer') and privacy guarantees ('No wallet address, token, transaction hash, query, or free-form text is published'). These details complement 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three dense sentences carry the precondition, core behavior, cardinality constraint, privacy guarantee, and sibling routing. The most important usage condition is front-loaded, and every sentence earns its place without repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with four fully documented parameters and an output schema, the description covers when to call it, what it reports, its limits, its privacy behavior, and what to use instead after payment. 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already documents all four parameters with 100% coverage, including enum meanings and the private nature of paymentOffer. The description reinforces the closed-vocabulary nature and non-publication behavior, but it does not add substantial new semantics beyond what the schema already 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.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Report' and the resource 'checkout blocker,' and immediately conditions it on a signed KnownFix checkout that cannot proceed before a payment hash exists. It also isolates the tool from siblings by explaining it reports exactly one closed-vocabulary blocker tied to the valid offer.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives an explicit precondition ('Use only after a signed KnownFix checkout cannot proceed before a payment hash exists') and an explicit exclusion ('Do not call after payment'), naming the alternatives get_fix, get_skill, and audit_endpoint. This leaves no ambiguity about when to use the tool versus its siblings.

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

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

Annotations are all false, so the description carries the full behavioral burden and does so richly. It discloses non-retroactivity of tickets, one free redemption via check_request, no collection of contact details, and important publish-safety constraints about secrets, tokens, internal hostnames, and file paths.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and then adds only necessary behavioral rules: already-stocked handling, ticket redemption, non-retroactivity, privacy, and publish safety. Every sentence earns its place, and there is no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the complete request lifecycle, redemption policy, privacy, and publish safety. Since an output schema exists, return-value details do not need to be described, and there are no obvious gaps an agent would need to safely invoke this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds significant semantics for publish, explaining that it controls public wanted-board visibility and warning against sensitive content, which the schema does not provide. Context and signature semantics are adequately left to the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Ask for a fix this store does not have yet' — a specific verb plus resource. It also distinguishes itself from related tools by describing the two outcomes (already stocked returns an id with no ticket; otherwise a ticket is created), which separates it from check_request, get_fix, and submit_fix.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear usage context: use this tool when requesting a fix the store lacks, and it explains the already-stocked shortcut. It also names check_request as the later redemption path. However, it does not explicitly name sibling alternatives such as submit_fix or search_fixes, or state when not to use the tool.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral detail: up to three ranked matches, what a free top match includes, what a paid top match includes, and the explicit instruction not to call get_offer. This goes well beyond the annotation baseline.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the most important usage rule, followed by return behavior, then sibling routing. Every sentence earns its place, and the dense second sentence packs essential free/paid distinction and redemption behavior without unnecessary filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given one parameter, rich annotations, and an output schema, the description covers all necessary context: when to use, what results look like, how paid vs free matches behave, and how to route to alternatives. No critical calling information is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single query parameter already has 100% schema coverage with detailed guidance on preserving exact error text, adding disambiguating context, and omitting sensitive data. The tool description restates the triggering condition but does not add substantial new 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.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action (search), resource (verified fixes), and when to use it (exact error or distinctive symptom). It also differentiates from siblings by naming list_catalog, get_fix, and request_fix as alternatives with distinct conditions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance is provided: use this first for exact errors, browse with list_catalog, use get_fix only with a known id or payment proof, use request_fix only after an honest miss, and explicitly do not call get_offer. This gives an agent clear routing rules with no ambiguity.

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

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

Beyond the annotation booleans, the description discloses meaningful behavior: submissions are operator-reviewed, reproduction is required for verification rather than trust, the returned submissionId is private, and submitted text/contributor details are never returned by the status tool. It also flags revenue-sharing as planned but not live, preventing false expectations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is four dense sentences with no filler. It front-loads the core purpose, then covers the review workflow, verification requirement, return value, follow-up path, privacy guarantee, and future revenue-sharing state.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the rich input schema, existing output schema, and the workflow this tool participates in, the description covers everything an agent needs: the write action, review gating, required verification artifact, the returned submissionId, and the exact status tool to call next. No critical operational detail appears missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, and the description does not restate parameter names. It adds value by emphasizing that the fix must include a reproduction so it can be verified, and by reinforcing that contributor details remain private and are never exposed through check_submission.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Offer a fix for the catalog,' which is a specific verb plus resource, and immediately clarifies the review-before-listing lifecycle. It does not explicitly distinguish itself from related siblings like request_fix, but the purpose is clear and not merely a restatement of the title.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives strong post-call guidance: save the submissionId, call check_submission, and expect pending/accepted/declined/cataloged statuses. However, it does not explicitly say when to choose this tool over alternatives or when not to use it, so usage direction is implied rather than stated.

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