RecallScout

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

Annotations already cover read-only, idempotent, open-world, and non-destructive traits. The description adds meaningful behavioral context by stating exactly what data is returned and adding the important caveat that recalls are matched by make/model/year rather than per-VIN repair status. It does not cover rate limits or error handling, but for a read-only open-world tool the added data-scope detail is valuable.

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?

Three sentences, front-loaded with the core action and returned data, then usage guidance, then a crucial caveat. Every sentence earns its place and there is no 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?

With no output schema, the description must explain return values, and it does so comprehensively by listing the vehicle attributes, recalls, complaints, and safety ratings. Annotations cover the read-only/open-world safety profile, and the single required parameter is fully described. Nothing material is missing for an agent to invoke this 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 description coverage is 100%, so the baseline is 3. The description adds the 'US' constraint and reinforces the 17-character length, which supplements the schema's looser minLength=11 and maxLength=25 bounds. This extra geographic and format specificity justifies a 4.

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 ('Decode') and resource ('US 17-character VIN') and enumerates the returned data: year, make, model, trim, engine, safety features, recalls, complaints, and ratings. This clearly distinguishes it from the narrower sibling tools (get_vehicle_recalls, get_safety_ratings, etc.) because it aggregates all of them from a single VIN. However, it does not explicitly name those alternatives, so it stops short of 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?

The description gives clear when-to-use guidance: 'Use when the user shares a VIN or asks about a specific car they own or plan to buy.' It does not list when not to use this tool or explicitly name alternative tools for make/model/year queries, but the context is unambiguous.

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 the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower; the description adds real value by enumerating what comes back (defect, safety risk, remedy, manufacturer notes, affected vehicles). With no output schema, that return-shape disclosure is what an agent needs to judge usefulness, though pagination/not-found behavior is unaddressed.

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, zero filler, with the action and identifier front-loaded ahead of the conditional usage note and the return payload.

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?

Single fully-documented required parameter, annotations covering operation safety, and an inline enumeration of return fields standing in for the absent output schema. Nothing required 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% and already carries the example, so the baseline is 3; the description nudges higher by explaining where the value comes from ('often printed on a recall letter'), which helps an agent recognize a usable campaign number in a user's message.

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 (look up) and resource (one NHTSA recall) scoped to a single campaign number, with a concrete example. The 'one ... by its campaign number' phrasing cleanly separates it from the search_* recall siblings that return sets.

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?

Explicit trigger condition: 'Use when the user has a recall notice or campaign number.' This gives a clear when-to-use but does not name the alternative to pick when the user lacks a campaign number (e.g. get_vehicle_recalls or search_* recalls).

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 readOnly, idempotent, openWorld and non-destructive behavior, lowering the disclosure bar. The description adds a genuinely useful behavioral caveat beyond the structured fields: many low-volume vehicles are never tested, which anticipates empty results. It still does not describe rate limits or result formatting, but output schema is absent and the added caveat is meaningful.

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 resource and rating dimensions, followed immediately by the usage condition and a caveat. Every clause earns its place with no repetition 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 read-only lookup with full schema coverage and complete annotations, the description adds the remaining needed context: what ratings are returned, when to use it, and the common no-test-data case. Nothing an agent needs 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% and each of the three parameters has a clear description including examples and constraints. The description only restates 'by make, model and model year,' adding no semantic detail beyond what the schema already provides, 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?

States a specific verb (Get) and resource (NHTSA 5-Star Safety Ratings) and enumerates the exact rating categories returned (overall, frontal crash, side crash, rollover, rollover risk). It also scopes the lookup to a tested variant by make, model and model year, which distinguishes it from sibling recall/complaint tools without opening their schemas.

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 when to use it: 'Use when the user asks how safe a car is or wants to compare crash-test results.' That is clear context, though it does not name alternatives such as check_vehicle_by_vin or state when not to use this tool (e.g. for recalls or complaints).

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, open-world and non-destructive behavior, so the bar is lower. The description adds genuine context beyond them: the data is unverified owner reports rather than confirmed defects, which shapes how an agent should word its answer. No pagination or auth caveats, but this is a read-only summary tool.

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?

Three dense, front-loaded sentences: one for what the output contains, one for when to invoke, one for the data-provenance caveat. No filler and no repetition of the tool name or schema.

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, but the description enumerates the returned fields and the caller-controlled excerpt count. Given a simple 4-parameter read-only tool with fully documented parameters and complete annotations, nothing an agent needs to call or interpret 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 description coverage is 100%, with each of make, model, model_year and recent_limit documented with ranges, defaults and examples, so the baseline is 3. The description only echoes 'by make, model and model year' and gestures at 'most recent complaint excerpts' for recent_limit, adding no syntax or constraint detail 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?

States a specific verb (summarize) and resource (NHTSA owner complaints) plus the exact output facets: counts, crashes, fires, injuries, top problem areas, recent excerpts. This clearly separates it from sibling tools like get_vehicle_recalls, get_recall_details and get_safety_ratings.

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 trigger: 'Use when the user asks about common problems, reliability issues or what owners report about a car.' However, it never names the alternatives or states when NOT to use it (e.g., prefer get_vehicle_recalls for confirmed defect/recall questions), which is exactly the sibling boundary that matters here.

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 openWorldHint, so the safety profile is covered. The description adds real behavioral value beyond them: records are ordered newest first and include defect summary, safety risk, remedy, and NHTSA do-not-drive/park advisories.

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, no filler, with the core capability front-loaded and the usage condition second. Every clause 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?

There is no output schema, and the description compensates by enumerating the returned fields and their ordering. Combined with the routing rule and required params, an agent has everything needed to call 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?

All three parameters are fully documented in the schema (100% coverage, with examples and bounds), so the schema carries the load. The description only restates that lookup is by make, model and model year, adding no new syntax or matching guidance.

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 (list NHTSA safety recalls for a vehicle), plus scope details: keyed by make/model/model year, ordered newest first, and what each record contains. The VIN exclusion cleanly separates it from check_vehicle_by_vin.

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?

Explicit when-to-use ('when the user names a car and asks about recalls or known safety defects') and an explicit when-not ('not a VIN'). It stops short of naming the alternative tool (check_vehicle_by_vin) or distinguishing it from get_recall_details, but the routing rule is 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 cover read-only, idempotent, open-world and non-destructive traits, so the bar is lower. The description adds real value by disclosing result ordering (newest first) and the shape of returned data (affected models, manufacture date window, defect, risk, free remedy), which the annotations do not provide.

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?

Three tight sentences, front-loaded with the core action and scope, then usage trigger, then practical owner guidance. No filler, no repetition of the title.

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 usefully enumerates the returned fields and coverage window, and annotations handle safety semantics. Only minor gaps remain (pagination, behavior on zero matches, whether brand is required), which are not critical to 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 schema documents brand and model with examples, making 3 the baseline. The description's 'by brand and/or model' adds genuinely useful semantics: either parameter can be used alone, matching the zero-required-parameter design and the OR search logic.

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 NHTSA safety recalls for child car seats/boosters), gives scope (2010 onward, sorted newest first), and is clearly distinguishable from siblings like get_vehicle_recalls and search_product_recalls by naming the child-seat domain.

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 to use it 'when the user asks whether a car seat, infant seat or booster is recalled,' plus adds post-search guidance on comparing manufacture date and model number. It does not name a competing sibling or a when-not condition, so it stops short of the top tier.

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 the safety profile (readOnly, idempotent, openWorld, non-destructive), so the description's added value is the ordering guarantee, the weekly publication cadence with multi-day lag caveat, and the coverage boundary. That is meaningful context beyond structured fields, though return-shape detail is only partial.

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 core action, then layers filtering, scope exclusions, and freshness in tight sentences. No filler and every sentence carries information an agent can act on.

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 compensates by listing return fields (product, reason, lot codes, distribution regions, severity class) and adds the freshness caveat, so an agent knows what to expect without inspecting anything else.

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 earns a bump by clarifying query semantics ('Leave the query empty to list the latest recalls') and giving concrete example values (peanut butter, listeria, cucumbers) that map the free-text field beyond the schema's terse description.

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+resource ('Search US FDA food recall enforcement reports') and immediately scopes it with ordering ('newest first') and filter dimensions, which cleanly separates it from search_product_recalls and search_car_seat_recalls.

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?

Explains the empty-query behavior ('list the latest food recalls') and draws an explicit boundary against USDA-covered meat/poultry/eggs. It gives clear when-to-use context, though it doesn't name a specific sibling to redirect to for those excluded products.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: results are ordered newest first, and the specific fields returned (hazard, remedy, injuries reported, where sold, company contact, official recall page). It does not mention pagination or result limits.

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?

Three sentences, all earning their place: purpose and search facets first, return contents second, domain exclusions last. No filler or repetition of the title.

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 read-only search with no output schema, the description covers purpose, valid inputs, result ordering, returned fields and domain boundaries. An agent has everything needed to decide to call it and interpret the response; absence of an output schema is compensated by the enumerated return fields.

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 single 'query' parameter is already documented with its 2-80 character bounds; the baseline would be 3. The description adds concrete query-value examples (crib, stroller, space heater, magnets, brand name) that clarify what kind of keyword string the schema's generic 'Product type, brand or hazard keyword' accepts.

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 (Search) and resource (US CPSC product recalls) with scope constraints: searchable by product, brand or hazard keyword, newest first. It is clearly distinguishable from siblings like search_food_recalls, search_car_seat_recalls and get_vehicle_recalls because it names the exact domain it covers.

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 states when to use it ('Use for household, children's and consumer products') and when not to ('Not for vehicles, car seats, food or medicines'), effectively routing the agent to the correct sibling tools. This is exactly the when/when-not/alternatives pattern.

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