VIN Decoder + Recalls: Bulk NHTSA Specs & Safety Recalls

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

Annotations already declare read-only, open-world, non-idempotent, non-destructive, but the description adds the operationally decisive facts annotations cannot carry: it runs the named Apify Actor on the caller's own account, costs $0.001 per VIN decoded, undecodable VINs are skipped free, run_max_charge_usd caps spend, and setting maxResults above run_max_items can bill more than is returned. It also discloses timing (5-15 s typical, 300 s max) and the remedy for a timeout error.

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?

Purpose and sibling routing are front-loaded in the first two sentences, which is right. However the definition is dense to the point of redundancy: the vehicle attribute list appears twice (once as a spec parenthetical, once inside the Returns enumeration), and the Parameters sentence largely duplicates what the 100%-covered schema already says, so several clauses do not earn their 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 an 8-parameter tool with no output schema, the description covers what the schema cannot: it enumerates the returned fields including recallCount, parkItRecall, complaintCount and the XLSX/CSV artifacts, and states the envelope shape ({actor, count, items}) plus the structuredContent/trimming behavior. Cost model, timeout recovery, and invalid-VIN handling are all addressed, leaving no material gap 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 coverage is 100%, so the baseline is 3 and the description mostly restates parameter intent (vins deduped, includeInvalid skipping, maxResults as a cost cap) rather than adding to it. It earns the bump for one genuine cross-parameter interaction the schema never states: run_max_items fills maxResults when unset and therefore bounds billing, while a higher maxResults can bill more than is returned.

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?

"Bulk-decode vehicle identification numbers with the official NHTSA vPIC API and attach NHTSA recall campaigns and complaint counts" gives a specific verb (decode), a specific resource (VINs/vehicle specs), and a compound scope (specs + recalls). It then explicitly separates itself from product_recall_monitor (FDA/CPSC product recalls) and company_website_enricher (firmographics), so an agent can disambiguate without opening any schema.

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?

Names positive personas and use cases (dealers, fleets, insurers, marketplaces, repair shops needing specs plus open recalls for many VINs) and gives explicit exclusions with the correct alternative named for each (product/drug recalls -> product_recall_monitor; title/lien history -> neither this nor any sibling). This is a full when/when-not/alternatives routing statement.

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