Macfax

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by listing exactly what information the tool returns (flags, price band, report status) and emphasizes 'Facts, not verdicts,' which aids in understanding the tool's behavior.

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

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

The description is a single sentence that front-loads the purpose and then lists outputs. It is reasonably concise for the amount of information provided. Could be broken into shorter sentences or bullet points, but it is effective.

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 tool's moderate complexity (2 parameters, no output schema), the description adequately explains the return value by listing the key pieces of information. It does not cover error cases or edge scenarios, but for a straightforward check tool, it is 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?

Schema description coverage is 100% with clear parameter descriptions. The tool description adds context by specifying that the URL can be from specific marketplaces (eBay, Craigslist, etc.) and that the id comes from search results, slightly enhancing understanding beyond the schema.

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 provides a trust picture for a specific listing via URL or listing ID, listing specific outputs like quality gates, flags, price comparison, etc. It distinguishes from sibling tools like search_mac_listings (which returns multiple listings) by focusing on a single listing.

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 when to use the tool: when you have a URL or listing ID and need trust information. It implicitly distinguishes from sibling tools but does not explicitly state when not to use it or mention alternatives. Still clear and helpful.

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 only indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds significant behavioral details: first alert stays inactive until email owner clicks confirmation link, no email before that, every alert email includes manage/unsubscribe links. This fully compensates for lack of annotation detail.

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 concise sentences plus a detailed consent contract paragraph. Every sentence adds value without redundancy. The purpose is front-loaded, and the behavioral details are efficiently presented.

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 creation tool with no output schema, the description covers the alert lifecycle, consent, and confirmation. However, it does not mention what the tool returns (e.g., alert ID or success status). Still, the key context for using the tool is sufficiently provided.

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 57%, but the description adds important meaning for the 'email' (user's own, confirmation required) and 'config' (Macfax config key with examples). For optional parameters like 'max_price_usd', the schema description is already clear. Could further explain 'min_tier', 'under_typical', etc., but the key parameters are well-covered.

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 creates a standing alert for used Mac listings, using Macfax to email the user. It distinguishes from sibling tools like search_mac_listings by specifying it is a watch/alert mechanism.

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 consent contract: create only for users who explicitly requested the alert. Details the confirmation process and that nothing is emailed until confirmation. Lacks explicit when-not-to-use or alternatives, but the context is sufficiently clear.

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=true, idempotentHint=true, destructiveHint=false. The description adds value by clarifying that all figures are asking prices from live listings, never sold prices. This provides additional behavioral context beyond the annotations.

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

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

The description is two sentences long, front-loading the key outputs and then adding usage context and a clarifying note. Every sentence serves a purpose with 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?

Given only one parameter and no output schema, the description fully explains what the tool returns (median, p25, p75, sample size, per-channel medians, net-to-seller, MSRP retention, trade-in floor) and the data source. No additional information is needed for an AI agent to understand and invoke the 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 single parameter 'config' has 100% schema coverage with a clear description of the format and examples. The tool description does not add further parameter semantics, but the schema already adequately explains the parameter. Baseline score 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 specifies exactly what the tool does: returns asking-price statistics for a given Mac configuration, including median/p25/p75 price, sample size, per-channel medians with net-to-seller, MSRP retention, and trade-in floor. This clearly distinguishes it from sibling tools like 'check_mac_listing' or 'search_mac_listings'.

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 states it is useful for pricing a Mac to sell or judging the fairness of a listing. While it doesn't explicitly state when not to use it or mention alternatives, the context is clear and the sibling tools provide natural alternatives for different needs.

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=true, idempotentHint=true, destructiveHint=false. The description adds value by disclosing the 'superseded' status behavior and explaining what data the report contains, which is beyond the annotations.

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

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

Two sentences plus a note on superseded status. Every sentence serves a purpose: first sentence defines the tool, second sentence gives usage context, and the note adds behavioral guidance. 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 tool with one parameter and annotations covering safety, the description is complete. It explains what the report provides, when to use it, and how to interpret the status. No gaps given the 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?

Schema coverage is 100% for the single parameter 'report_id'. The description repeats the schema description ('8-character report id from a macfax.com/r/<id> URL') without adding new details. 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 states the tool fetches a verified Macfax report with specific data elements (hardware identity, Activation Lock/MDM checks, etc.). It distinguishes from sibling tools like check_mac_listing or lookup_mac_serial by focusing on fetching reports from a macfax.com/r/ link.

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 says 'Use when a listing or seller shares a macfax.com/r/ link and the buyer wants the facts behind it.' Provides guidance on interpreting 'superseded' status. However, it does not explicitly mention when not to use or alternatives, though siblings are distinct enough.

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?

Description adds behavioral details beyond annotations: explains behavior for post-2021 serials (randomized, no encoding), states it is advisory, and clarifies what it does not verify. This complements the readOnlyHint and idempotentHint annotations well.

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 concise, front-loads the core purpose, and every sentence serves a purpose—covering function, behavior for different serial types, and limitations. No unnecessary 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 lookup tool with one parameter, no output schema, and robust annotations, the description covers all necessary aspects: what it does, edge cases, limitations, and alternatives. It is complete for its scope.

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 already describes the serial parameter well (100% coverage). The description adds context on what information is decoded from the serial, but does not significantly extend beyond schema descriptions. Still, it adds value by explaining the output derived from the parameter.

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 it checks a Mac serial number for Macfax report existence, model/year decoding for pre-2021 serials, and format check for newer ones. It distinguishes itself from siblings like check_mac_listing or get_mac_report by focusing solely on serial lookup.

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 notes limitations ('cannot verify condition, Activation Lock, or possession') and suggests 'a Macfax report can' for deeper checks, providing guidance on when to use this tool versus alternatives. However, it does not directly contrast with sibling tools.

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 value by detailing the pre-filtering (scam clusters, junk titles, etc.) and deep-linking behavior. It does not contradict 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?

The description is two sentences, front-loaded with the core action and immediately followed by key features. 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 10-parameter search tool without an output schema, the description is fairly complete: it explains the data source, pre-filtering, and available filters. However, it omits details on sorting, pagination, and output format, which would enhance completeness.

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 only 40% schema coverage, the description compensates by explicitly listing filter criteria (configuration, family, chip, RAM, storage, price ceiling, verified-report tier), mapping to most parameters. Sort, year, and limit are not covered, but the description adds significant meaning beyond the schema.

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 purpose: searching live used-Mac listings aggregated from multiple sources with pre-filtering. It distinguishes itself from sibling tools like check_mac_listing (specific listing details) and get_mac_price_stats (statistics).

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 use for finding available Macs but lacks explicit guidance on when to use alternatives such as check_mac_listing or get_mac_price_stats. Sibling tool names provide context but the description itself does not offer usage criteria.

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