KnownFix

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

With no annotations, the description carries the burden. It mentions 'Free' and 'machine-readable report with remediations,' adding useful output details. However, it does not disclose that the tool will make outbound HTTP requests to the target URL, potential side effects, or limitations (e.g., public URL required).

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: three sentences that front-load the purpose, then detail checks and output. Every sentence contributes value—no filler or repetition of schema 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?

For a single-parameter tool with no output schema, the description covers the action, the specific audit categories, and the return format. It could elaborate on the grading scale or response schema, but the essentials are present, making it fully usable in most scenarios.

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%, with the param description 'Base URL to audit, e.g. https://your-agent.example.com' clearly defining the input. The tool description reinforces the 'agent-facing URL' aspect but adds no new syntax or format details beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a readiness audit for agent-facing URLs, listing specific checks (MCP handshake, CORS, discovery docs, payment-offer behavior). This distinguishes it from sibling tools that focus on fixes, offers, and catalog, making the purpose unambiguous.

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

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

The description implies the use case: run this on a URL to assess readiness. It provides a concrete example (KnownFix self-audit) but does not explicitly state when not to use it or name alternatives. Since no sibling tool performs audits, the implicit guidance is sufficient.

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?

With no annotations provided, the description carries the full behavioral disclosure burden. It reveals key behaviors: free samples are immediate, paid entries require a mined on-chain payment to the treasury on Base mainnet chain 8453, and one payment redeems one fix. It does not cover failure modes or return formatting, but the disclosed payment mechanics are substantial and non-obvious.

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 and front-loaded with the core action ('Get a fix body'). The subsequent sentences each add essential payment behavior and chain specifics without redundancy. Every sentence earns its place.

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

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

For a tool with no output schema and no annotations, the description provides enough context to guide invocation: it explains free versus paid, the payment prerequisites, the chain, and where to obtain the id. It leaves some gaps (e.g., error behavior for unpaid entries, exact response structure), but these are arguably outside the minimum needed to select and invoke 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by specifying that paymentTx must be a 'mined payment of perFixWei to the treasury on Base mainnet chain 8453,' which details the exact on-chain conditions. This supplements the schema's simpler '0x-prefixed tx hash of your on-chain payment' with valuable specifics.

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 begins with 'Get a fix body,' a specific verb+resource pair that clearly identifies the tool's purpose. It distinguishes itself from siblings (get_offer, list_catalog, search_fixes, submit_fix) by focusing on retrieving the actual fix content rather than offers, listings, or submission.

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 provides clear usage context: free-sample entries return immediately, while paid entries require a paymentTx. It explicitly references get_offer for payment details and mentions that the id comes from search_fixes or list_catalog, giving the agent a clear workflow. It stops short of explicitly saying 'do not use this for offers or listings,' but the guidance is strong.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes what the offer contains but does not explicitly state that this is a read-only operation, what side effects (if any) occur, or what the return format looks like. The phrase 'machine-readable offer' hints at a data retrieval, but it is not explicit.

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 a single, compact sentence that front-loads the key information. Every word adds value, and it is immediately scannable.

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 parameterless getter, the description adequately lists the returned content. It could mention the format or any traversal details, but given the tool's simplicity, the description is largely sufficient.

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 baseline of 4 applies. There is nothing to explain or disambiguate.

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 the resource ('the machine-readable offer') and lists its key fields (price, treasury address, chain, redemption route), making the tool's purpose clear. The verb is implicit ('get' in the name), and the resource is distinct from sibling tools like get_fix or submit_fix, so it differentiates well.

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 provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, intended scenarios, or exclusions. The agent must infer usage solely from the tool name and description.

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?

With no annotations, the description must fully disclose behavior. It mentions that it returns the full free tier, but does not clarify that this is a read-only operation, nor does it mention potential size, pagination, performance implications, or any access restrictions. The description focuses on content rather than behavioral characteristics.

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 a single, well-structured sentence that front-loads the key information ('The full free tier') and efficiently lists the included data points. Every word contributes, with no 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?

For a zero-parameter tool with no output schema, the description explains what data the catalog includes, which is the main missing piece. It could be slightly more explicit that the tool lists all catalog entries, but given the simplicity and sibling context, this is largely complete.

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 is trivially complete. The description adds context about what the returned catalog contains, which is helpful even though no parameter explanations are needed. Given the baseline of 4 for zero-parameter tools, this 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 makes clear the tool provides the full free tier of catalog data, enumerating the included fields (error signature, title, tags, confidence, free sample status). The verb is implied by the name 'list_catalog', and the content scope distinguishes it from siblings like get_fix or search_fixes, though it could be more explicit about listing all entries.

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?

No guidance is given on when to use this tool versus its siblings. There is no mention of alternatives, such as using search_fixes for filtering or get_fix for a specific entry, nor any indication of appropriate use cases (e.g., 'use this to browse the entire catalog').

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?

With no annotations, the description carries the full burden. It discloses the return format ('ranked candidate fixes with confidence labels') and the meaning of an empty result ('an honest miss'), which is valuable behavioral context. It doesn't explicitly state side effects or auth requirements, but as a search tool this is less critical.

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, then the specific usage instruction and return behavior. Every clause adds value without fluff 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?

For a simple tool with one parameter and no output schema, the description covers what it does, how to use it, what to expect (ranked results with confidence labels), and how to interpret an empty result. This is fully sufficient for an agent to select and invoke it correctly.

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

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

The schema already fully documents the single parameter 'query' with 'The error message or symptom, verbatim' (100% coverage). The description adds 'Paste the error text verbatim' but this largely restates the schema. There is no additional parameter-level meaning beyond what the 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?

The description clearly uses a specific verb ('Search') and identifies the resource ('KnownFix'), and explicitly states the output: 'ranked candidate fixes with confidence labels.' This distinguishes it from siblings like get_fix (retrieving a specific fix) and list_catalog (listing all fixes).

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 provides concrete usage guidance: 'Paste the error text verbatim,' which tells the agent exactly how to format the query. It also implies the use case ('for your error') and notes the tool is free, but it does not explicitly mention when to use alternatives like get_fix or submit_fix.

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?

With no annotations provided, the description carries the full burden of disclosure. It openly states that submissions are not immediately listed but operator-reviewed, and that revenue sharing is planned but not live. These are meaningful behavioral traits beyond the raw schema that help the agent set expectations.

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

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

The description is three sentences and every sentence earns its place: purpose, review process/verification need, and a revenue-sharing caveat. It is front-loaded with the core action and avoids unnecessary 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?

The tool has 6 parameters, no output schema, and no annotations, yet the description covers key contextual points like review delay and verification. However, it does not indicate what the response looks like (e.g., a confirmation ID or next steps), nor does it clarify the remaining undocumented parameters. It is adequate but not complete.

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 50%, with meaningful descriptions for signature, contributor, and reproduction. The description adds context for reproduction ('so the fix can be verified'), but it does not clarify 'fix', 'cause', or 'title', which lack schema descriptions. It partially compensates but leaves gaps.

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

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: 'Offer a fix for the catalog.' This clearly identifies the tool's action and target, and the phrase 'submissions are reviewed by the operator before listing' differentiates it from the sibling read tools (get_fix, search_fixes, etc.).

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 provides clear context for when to use the tool: to submit a fix that will be reviewed. While it doesn't explicitly name alternatives or say 'use this instead of...', the wording implies it's the submission counterpart to the read-only siblings. The instruction to include a reproduction gives actionable guidance.

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