Apibara Vehicle Auction Data

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, and the description adds only a 'supported' qualifier indicating results are restricted to supported routes. It does not describe return payload or empty/error behavior, but the annotation safety profile covers the main behavioral burden.

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?

A single sentence with no filler, front-loading the verb and resource. The mismatch between title 'Calculate' and description 'Retrieve' is a minor wording issue.

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 an anyOf input contract, the description is too thin: it omits how the port/port_id parameters participate and what response shape to expect. An agent could guess the input contract only partially.

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%, so the description must compensate. It explains vin and lot_number as accepted lookup keys but never explains port/port_id or the anyOf one-of requirement. This partial coverage earns a 2.

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 ('Retrieve'), a concrete resource ('auction-to-port shipping information'), and the accepted identifiers ('VIN or lot number'), distinguishing it from the vehicle-listing siblings. The title reinforces the resource. It lacks an explicit exclusion of sibling tools, so not a 5.

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?

Gives a conditional context: use when location and route data are available, with identifier choice. It does not name alternatives or when-not conditions, but none of the sibling tools cover shipping, so the context is fairly 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, and destructiveHint=false. The description adds useful context beyond that by specifying the operation is authenticated and tied to the supplied X-API-Key, and confirms a read-only 'retrieve' behavior. No contradictions.

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?

A single, front-loaded sentence with no filler. Every phrase ('Retrieve', 'authenticated API usage', 'current plan limits', 'supplied X-API-Key') carries meaningful information for a zero-parameter tool.

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 read-only status/usage tool, the description is largely complete: it identifies the operation, resource, and authentication context. It does not describe the exact response shape, but the simple nature of the tool and the safety profile from annotations make that a minor gap.

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 and schema coverage is 100%, so the baseline is 4. The description usefully clarifies that the X-API-Key is the authentication context rather than an input parameter, which prevents an agent from hunting for a parameter that does not exist.

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 ('Retrieve') and names a precise resource: authenticated API usage and current plan limits for the X-API-Key. This clearly differentiates it from sibling tools like calculate_shipping or get_vehicle, all of which concern different domains.

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 clear usage context: whenever authenticated API usage or current plan limits are needed. Although it does not explicitly name alternatives or exclusions, the sibling tools are so unrelated that an agent can confidently choose this tool without further 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds only the phrase 'supported auction vehicles' and does not disclose pagination behavior, result shape, or the relationship semantics, but it does not contradict 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 a single sentence with no filler and the action is front-loaded. However, the phrase 'related supported auction vehicles' is somewhat vague, and the brevity comes at the cost of semantic precision.

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 annotations and schema cover safety, identifier format, and pagination bounds, but the central concept of 'related' is never defined. An agent cannot tell whether related means same model, same location, similar specifications, or something else, which is a clear gap for a tool whose entire purpose depends on that relation.

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 only 50%: identifier is described as 'VIN or slug_vin accepted by the canonical vehicle detail endpoint,' but per_page has no description beyond min/max constraints. The tool description itself adds no parameter context, so the meaning of per_page and the precise role of identifier remain under-specified.

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 ('Retrieve') and resource ('related supported auction vehicles'), so the basic purpose is clear. However, it does not define what 'related' means, and it does not explicitly differentiate itself from siblings like get_vehicle or search_auction_vehicles.

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?

There is no guidance on when to use this tool versus alternatives such as get_vehicle, get_vehicle_history, or search_auction_vehicles. The schema comment about the 'canonical vehicle detail endpoint' hints at identifier compatibility but does not explain when this tool is the right choice.

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, and destructiveHint=false, covering the safety profile. The description adds only the notion of 'supported vehicle' and 'canonical detail endpoint,' but does not disclose return format, error handling, or what 'supported' means. This is acceptable but not enriching.

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 with the verb and resource front-loaded. There is no filler or redundant elaboration, making it highly 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 single-parameter get-by-identifier tool with full schema coverage and strong annotations, the description is nearly complete. The only notable omission is the response payload or not-found behavior, but the lack of an output schema and the tool's simplicity make this a minor gap.

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%; the identifier parameter already has a detailed description matching the tool description almost verbatim. The description adds no new meaning beyond rephrasing the schema, so it stays at the baseline.

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 (retrieve), a specific resource (one supported vehicle record), and the accepted identifier types (VIN or slug_vin). This clearly differentiates from siblings like search_auction_vehicles or get_vehicle_history, which serve different retrieval purposes.

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 intended usage is implied: use this tool when you have a VIN or slug_vin and need the canonical single vehicle record. However, it does not explicitly mention alternatives or exclusions, leaving the agent to infer when to choose get_vehicle over 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=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds the word 'current', implying the supported filters may change over time, which is useful. It does not disclose other behavior like rate limits or whether the result is exhaustive, but with strong annotations, this is acceptable.

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

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

The description is a single, front-loaded sentence with no wasted words. Every word contributes to the purpose and context.

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, optional-parameter metadata tool, the description covers the basic purpose, but since there is no output schema, it should say more about what the filter metadata looks like and how the platform parameter affects the result. The missing parameter semantics leave an agent uncertain about correct invocation.

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%, so the description must compensate for parameter meaning. It does not mention that the 'platform' parameter selects between copart and iaai, nor what happens when it is omitted. The enum values in the schema are self-explanatory, but the description adds no value to parameter understanding.

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 ('Retrieve') and a specific resource ('current supported filter metadata'), and states its intended application ('for search UIs and integrations'). This clearly distinguishes it from siblings like get_vehicle or search_auction_vehicles, which operate on vehicle data rather than filter metadata.

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 phrase 'for search UIs and integrations' gives clear context on when to use the tool. However, it does not explicitly state when not to use it or name alternative tools, so it stops short of a full exclusion-based 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 establish read-only, idempotent, open-world, and non-destructive behavior. The description adds useful beyond-annotation context: data is retained ('retained'), may be absent ('when available'), and is not a complete ownership/accident history. 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 purposeful sentences with the core action and caveat front-loaded. No filler or repetition of schema details.

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, one-parameter read-only lookup with rich annotations, the description covers data source, availability caveat, and limitations. The lack of output schema is acceptable because the history concept and scope are clear enough to 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?

The schema already fully documents the sole identifier parameter (VIN or slug_vin), so the description doesn't need to compensate. It adds marginal framing ('one supported vehicle') but no new parameter-level semantics.

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 concrete verb and resource ('Retrieve retained Copart + IAAI auction history') and scopes it to one supported vehicle, which separates it from sibling tools for vehicle details, related vehicles, and search. The negative clause also distinguishes it from ownership/accident-history lookups.

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 signals when this tool applies: for a single supported vehicle's auction history, when available, and explicitly warns that it is not a complete ownership/accident record. It does not name alternative sibling tools explicitly, but the scope plus caveat gives enough selection context.

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, and destructiveHint=false, which covers the safety profile. The description adds minimal context by implying it returns only 'supported' locations, which suggests a curated list, but no additional behavioral details (e.g., filtering, pagination) are disclosed. With annotations covering safety, a 3 is appropriate as the description adds a small amount of value.

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, concise sentence with no wasted words. It is front-loaded with the core action and resource. However, it is so brief that it under-specifies key aspects, but conciseness itself is not the issue; the sentence is appropriately compact for what it conveys.

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 four optional parameters, no required ones, and no output schema. The description does not explain the parameters, return format, or any usage details. An agent calling this tool would not know how to filter results or interpret the response. Given the low schema coverage, the description fails to provide essential context for correct invocation.

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%, meaning no parameter explanations are provided in the schema. The description does not compensate at all; it never mentions the parameters (s, state, country, platform). An agent has no idea what 's' or 'state' means or how to use them. The only parameter with a clear meaning is 'platform' due to its enum, but the description adds nothing to explain the others.

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 clear verb ('retrieve') and resource ('supported auction facilities and locations'), which distinguishes it from sibling tools focused on vehicles (e.g., get_vehicle, search_auction_vehicles). It is specific about the resource type, though it does not explicitly differentiate itself from siblings by name.

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 alternatives. The description only states what it does, leaving the agent to infer that it is for listing locations, but no explicit when/when-not or alternative references are provided. Sibling tools are mostly vehicle-related, so the intended context is implied but not stated.

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 it readOnly and idempotent; the description adds that it covers 'supported' auctions and that fields can be nullable and source-dependent. This is useful but does not disclose pagination, output shape, or source-specific behaviors.

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 with no padding; the core action and a key caveat are front-loaded. Efficient and readable.

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 an 18-parameter search tool with no output schema and only 6% parameter description coverage, this terse description leaves major gaps around filter combination, pagination, and source-specific behavior. An agent would have to infer most semantics from names and enums.

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?

Only one of 18 parameters has a schema description (s), and the description does not compensate by explaining param semantics. The note about exact filters and nullability is generic and not enough to understand the large optional filter surface.

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 it searches supported Copart and IAAI vehicle auction records, with a clear verb and resource. It distinguishes from sibling get/list tools by framing this as a multi-record search, though it does not name any sibling explicitly.

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?

Gives a directive to use exact documented filters and warns fields are nullable/source-dependent, but does not state when to choose this over siblings like get_vehicle or list_auction_locations. No exclusions or alternatives are provided.

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