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?

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?

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 establish readOnly, idempotent, and non-destructive behavior, so the bar for supplemental disclosure is lower. The description adds valuable behavioral detail about the return contents: bounded scope, deliverabels, delivery time, limitations, sample-report links, and exact prices. 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?

Two dense, front-loaded sentences with no filler. The first sentence states comparison purpose and scope; the second lists return fields and the next-step guardrail. Every clause 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?

With no parameters, an output schema present, and annotations covering side-effect safety, the description supplies the remaining essential guidance: what to compare, what data to expect, and when to call order_service. Nothing important is missing 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.

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

The tool takes zero parameters and the input schema documents 100% coverage, so there is no parameter semantics for the description to supplement. This is the baseline expected for a parameter-less tool.

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 the specific verb 'Compare' and identifies the exact resource: KnownFix's $49 first-look report and deeper website, public-codebase, agent-commerce, and release-pipeline reviews. This clearly distinguishes it from generic sibling tools like list_catalog 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?

It not only states what the tool does but explicitly routes the agent: 'Call order_service only after choosing a service and confirming authority over the public target.' This provides both sequencing and a condition for advancing to the sibling 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 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 are all false, so the description carries the behavioral burden. It adds critical context beyond them: the order is private, the checkout is for Base USDC/ETH, and the returned svc_ ticket is shown once and is the only report-retrieval credential. This is not contradicted by annotations.

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

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

Four sentences each earn their place: core action, target scope, safety rule, and one-time credential warning. Information is front-loaded and there is no fluff.

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

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

For a 5-parameter order-creation tool with an output schema and all-false annotations, the description covers the action, eligibility constraints, safety requirements, and the most important return behavior. Nothing needed for a correct call 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?

With 80% schema coverage, the schema already documents notes, targetUrl, publishTarget, and authorizationConfirmed. The description reinforces the public-target/no-credentials rule but does not add new parameter-level meaning such as how serviceId values map.

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-plus-resource: 'Create a private ticket and signed Base USDC/ETH checkout for one published professional service.' It also scopes valid targets to public HTTPS sites/public GitHub repos, which separates it from list/check 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?

It clearly places the tool as the action for commissioning a published service and requires public targets and authorization. It does not name sibling alternatives or state when not to use, so it stops short of a 5.

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

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.