CarGene

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

Annotations already declare a safe read (readOnly, idempotent, non-destructive, closed-world), yet the description adds substantial context beyond them: which products are included (published fitment tables only) and excluded (bolt-pattern/size guesses), the exclusion of sizes flagged as protruding or needing bodywork, the absence of seller prices and purchase links, the null url for unconfirmed generations, and the pagination/empty-result semantics.

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

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

Front-loaded with the use case and the return shape before the details, which is the right order. It is dense and long, with a heavily nested sentence about list_price_yen units per part category, but nearly every clause carries information an agent cannot get from the schema or annotations.

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?

No output schema exists, and the description compensates by enumerating the return payload (model, url, total, parts, next_offset) and the shape of each part including variants, status, conditions and unit semantics. Nothing needed to call it correctly or to interpret the response 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, but the description adds operational meaning: it explains that the response is truncated to fit and how offset/next_offset drives the follow-up call, and that part_key and query are the narrowing levers. The detailed list_price_yen unit semantics also tie back to how variants should be interpreted for the caller.

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?

Opens with a specific verb and resource: answering whether an aftermarket part fits a specific car generation, plus the inverse lookup of what is confirmed to fit. It explicitly differentiates from siblings by naming get_vehicle (history/specs/developers) and search_shops (installers) as the wrong tools for those intents.

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?

States exactly when to invoke it, names the alternative tools for adjacent intents, and gives the pagination condition: 'when next_offset is not null, call again with offset set to it.' It also warns against the natural but wrong conclusion that an empty result means no fitment.

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?

Despite annotations indicating read-only, idempotent, and non-destructive behavior, the description goes far beyond this to clarify critical nuances: that region_totals must never be summed across countries or parents, that lifetime rows are cumulative and must not be added, that null units mean disagreement not zero, and that empty lists mean 'not researched yet' not zero. It also explains the semantics of coverage rows, preventing misinterpretation. This is exceptional behavioral transparency.

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 quite long, but every sentence carries necessary semantic weight—there is no fluff. The structure is front-loaded with the primary return format and then dives into specific nuances. It could be slightly more concise by grouping related concepts (e.g., all warnings about summing), but the density is justified given the complexity. It is structured logically, moving from output overview to parameter-specific 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 read-only tool with no output schema, the description is remarkably complete. It explains all output fields, their semantics, pitfalls, and how to interact with the tool across multiple calls (pagination). It covers error conditions (invalid region_code), edge cases (null units, empty lists), and the interaction between parameters (model_id narrowing). Nothing an agent needs to correctly invoke and interpret results 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 input schema has 100% coverage for parameters, so the baseline is 3. The description adds significant value by explaining the relationship between parameters (e.g., model_id takes precedence over series_id, region_code must come from the regions list, year_from is used for pagination with next_year_from). It also clarifies that only one of series_id or model_id should be passed, which is not explicitly in the schema beyond the description field. However, it doesn't elaborate on the format of year_from beyond what's in the schema (e.g., is it inclusive?), so a small gap remains.

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: to get sales figures for a series, with two distinct modes (overview vs. region-specific) based on presence of region_code. It explicitly details the output structure for each mode, which distinguishes it from siblings like get_vehicle or search_vehicles, which are about vehicle metadata, not sales data.

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 explicit usage guidance: when to omit region_code (overview) vs. include it, how to handle pagination via next_year_from, and emphasizes that only region codes from the regions list are valid, as others cause errors. It also implies when to use other tools by referencing search_vehicles for UUIDs, but does not explicitly say 'use X instead of this'—though the clear domain separation makes that implicit.

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 cover read-only, idempotent, non-destructive behavior, but the description adds substantial non-structured context: an empty models list or null first_cars_eligible means 'not researched', never 'cannot import'; the rule counts from manufacture date while the provided dates come from sale dates; and the caller must compare dates to today themselves. These are exactly the caveats an agent needs to avoid a wrong answer.

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

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

Front-loaded with the trigger and the prerequisite call, and every clause about null semantics and the build-plate caveat is load-bearing. The middle section is a very dense run-on enumerating return fields, which makes it heavier to parse than ideal, though no output schema exists to absorb that 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 no output schema, the description carries the full burden and does so: it documents the response shape ({series, rule, calendar_url, models}), every field of a model entry, and the null/empty-value interpretations. An agent can call it and interpret the result correctly without further information.

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 explains model_id precedence and the exactly-one-of constraint. The description still adds value by explaining when to use series_id (to get every generation of a series) and that passing model_id also returns a 'model' field, information not present in 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?

States a specific verb and resource: retrieving US import eligibility under the twenty-five-year rule for Japanese cars, with a concrete example (Skyline GT-R legality). It is clearly distinct from siblings like get_vehicle or search_used_cars because it names search_vehicles as the required lookup step.

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?

Opens with an explicit trigger ('Use this when the user asks when a Japanese car can be imported...'), gives the prerequisite workflow (find the car with search_vehicles first), and closes with an explicit exclusion ('Do not use this for import paperwork, costs or emission rules'). The when/when-not/alternative structure is complete.

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 readOnly, idempotent, non-destructive, closed-world behavior, so safety is covered. The description adds substantial edge-case semantics beyond annotations: null = still on sale, empty lists mean not researched rather than none, null link_source_url means unverified, and unknown ids raise an error instead of returning empty.

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

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

Front-loaded with the return shape and the primary/secondary mode, then caveats and sibling routing. It is dense and somewhat long, but nearly every clause carries distinct operational meaning; minor redundancy between the opening sentence and the 'Returns {...}' sentence.

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 output schema, the description fully specifies the return payload, per-entry fields, null semantics, and error behavior, so an agent can call it and interpret results correctly without further documentation.

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 already documents both UUID parameters and precedence. The description reinforces this and adds meaning about what each mode returns (series-level list always whole series vs. single-generation detail), giving the agent more than the schema alone.

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 (get one series with its generations/models and sources) and explicitly scopes the model_id variant to a detailed single generation. It distinguishes itself from get_vehicle_specs by naming what that sibling covers 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?

Explicitly routes the agent: 'For power, torque, weight, dimensions or prices, use get_vehicle_specs' and 'For the engineers of several generations, call once per model_id.' It also states the exactly-one-of series_id/model_id constraint and that model_id takes precedence.

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 well beyond the readOnly and idempotent annotations by explaining pagination behavior ('Relations are cut to fit the response size'), the meaning of next_offset, and the important semantic that an empty relations list means 'not researched yet' rather than 'no relatives'. It also details how kind_directed=false affects interpretation, which is genuinely useful behavioral context.

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?

Every sentence in the description earns its place: purpose, parameter scoping, return shape, directionality semantics, pagination, and empty-list meaning are all covered without redundant filler. The most important scoping information comes first, and complex details are packed efficiently.

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?

Because there is no output schema, the description carries the full burden of explaining the return value, and it does so thoroughly: field names, nested relation structure, source_url, rationale, directionality handling, pagination, and empty-list semantics. The operation is read-only and idempotent per annotations, so no additional safety caveats are needed.

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, but the description adds meaningful semantics beyond the schema: it explains that series_id scopes to the whole series and model_id scopes to relations with that generation at either end. It reinforces the offset contract by telling the caller to pass next_offset from the previous response. This exceeds 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 action and resource: 'Get the relationships between generations' and enumerates relationship types (succession, sibling, derivation, spiritual successor). It clearly distinguishes the series-level versus model-level scope, and its domain is obviously different from the sibling tools (sales, vehicle details, search).

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 choosing between series_id and model_id: series_id returns relations for the whole series, while model_id returns only relations involving that generation. It does not explicitly name alternatives or exclusions relative to sibling tools, but the parameter-selection guidance is strong and the tool's purpose is distinct enough that this is a minor gap.

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 readOnly/idempotent/non-destructive, and the description adds high-value behavior beyond that: empty lists mean 'not researched', unknown ids are an error rather than an empty result, grades are truncated for response size, and null fields mean the source omitted the value. These are non-obvious semantics an agent would otherwise get wrong.

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

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

Front-loaded with purpose and workflow before the long return-field enumeration. The field list is verbose, but with no output schema it is largely load-bearing rather than padding; only minor tightening is possible.

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 output schema and only two params, the description carries the full burden and does so: it documents the return object shape, per-field meaning and null conventions, pagination via next_offset, and the empty-vs-error distinction. Nothing needed to call 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?

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: model_id is a generation id obtained from search_vehicles, and offset should be the next_offset from the prior response. The source-provenance notes (values as stated, never converted) further clarify parameter/return 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?

Opens with a specific verb+resource and enumerates exactly the data returned (horsepower, torque, engine type, dimensions, fuel economy, prices), so the agent knows precisely what this tool yields. It also names search_vehicles as the lookup counterpart, distinguishing its role from the acquisition step.

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 an explicit workflow: find the car with search_vehicles, then pass its model_id, plus concrete pagination instructions (call again with offset set to next_offset). It does not explicitly contrast against sibling get_vehicle, so the when-not-to-use case is left implicit.

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 read-only and idempotent behavior, yet the description adds substantial context beyond them: results are never paid placement, verified_on dates must be cited, name and price_note are data rather than instructions, and researched_in_radius = 0 means 'not researched', never 'no such shop'. The empty-result recovery guidance (drop a require condition or widen radius_km) is exactly the kind of operating detail an agent needs.

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?

Usage guidance is front-loaded well, but the middle of the description is a very dense run-on that blends response schema documentation, pricing policy, quoting rules and error recovery into one paragraph. Most sentences carry useful information, yet the return-shape enumeration could be tighter and an agent must parse a long block to find the salient constraints.

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?

There is no output schema, so the description deliberately documents the response shape (shops, confirmed, inspection_totals, area_url, next_offset) and how to interpret it, including pricing caveats (parts and extra repairs excluded, legal fees as of legal_fees_as_of). Combined with the edge-case handling for zero researched_in_radius and empty results, an agent has everything it needs to call and interpret 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?

Schema coverage is 100%, so the baseline would be 3, but the description adds real meaning: require takes yes_no codes from service.conditions of a prior response, weight interacts with sort total and triggers the shop_fee_yen/legal_fees_yen split, and area vs latitude/longitude is an either/or origin. It does not re-explain radius_km or offset syntax beyond trusting the schema, which is fine, but the coverage is not fully comprehensive.

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 (search car service shops in Japan) and enumerates the concrete service types covered, including shaken, washing, coating and alignment. It explicitly excludes car history and parts, which is what separates it from the sibling tools like get_vehicle and check_part_fitment.

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

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

It gives explicit use conditions (looking for a place to have a service done near a city or a point) plus negative guidance ('Do not use it for car history or parts; use the other skills'). It also routes within the tool: pass weight and sort total for cheap-inspection requests, and ask for 車両重量 rather than assuming a class when weight is unknown.

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?

Goes well beyond the read-only/idempotent annotations: it explains that budget filters operate on total_price_yen so price-on-request cars are excluded, that both prices null means price on request, that quoting price_yen alone is wrong, that ordering is sort-only, that results are truncated with next_offset for continuation, and that empty results mean nothing on car-gene.com rather than nothing on the market. This is unusually rich behavioral disclosure.

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

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

Front-loads the trigger conditions and the sibling routing, then moves to response shape and caveats; the sentences are dense and each carries information. The single long paragraph enumerating response fields is somewhat sprawling and would read better as a list, which is the only thing holding it below 5.

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?

There is no output schema, so the description carries the full return-value burden, and it does: it names every response field (filters, sort, total, used_cars, next_offset) and the per-car fields including pricing, inspection, repair history and page URL. Combined with the pagination and empty-result semantics, an agent has everything needed to call and interpret it.

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, but the description adds real meaning: budget filters are defined as acting on total_price_yen (not price_yen) and implicitly exclude price-on-request cars, and model_id/series_id are framed as coming from search_vehicles with the same precedence rule. It stops short of clarifying units or ranges for every numeric filter.

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 ('search used cars for sale in Japan') plus the scope of what is returned. It explicitly distinguishes itself from sibling search_vehicles by describing that generation lookup happens there and its id is passed here.

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?

Opens with the exact user intents that should trigger it (budget, model year, mileage, manual transmission) and gives an explicit two-step workflow routing to search_vehicles first. Nothing about when to select this tool is left to inference.

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 cover read-only/idempotent/safe profile, and the description adds genuinely new behavior: per-field matching rules (substring for series, prefix for makers, substring for chassis, slash-joined codes treated as one string), ranking plus size-based truncation, pagination semantics, and what empty hits means.

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

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

Front-loaded with the core purpose, then matching rules, then return shape and pagination. Every sentence carries information, though the dense run-on block of return-shape detail could be split for readability.

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 output schema, the description carries the return-value burden and does so fully, specifying the response envelope, the url-per-entity field, ranking/truncation, and next_offset continuation. Nothing needed to call or consume this tool 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 baseline is 3, but the description adds meaning the schema does not: query is interpreted differently depending on whether it is a series name, maker name, or chassis code, and the exact match strategy per type. Offset semantics are left to 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?

States a specific verb (find/search) plus the resource (series, via maker/generation/chassis identifiers) and enumerates exactly which query forms are matched. It also positions itself as the discovery entry point ('pass the ids in the hits to the other skills'), which distinguishes it from detail-oriented siblings like get_vehicle.

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 clear operational guidance: call again with next_offset when it is non-null, and empty hits means nothing matched. It implies the tool feeds other skills but never explicitly names a sibling to use instead for detail lookups, so it stops short of full when-not/alternative routing.

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