Car market prices

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

Annotations already declare readOnly, idempotent and openWorld, so the safety profile is covered; the description adds genuinely new behavior: the data is a daily snapshot ('today's prices'), it covers both used and zero-km cars, prices are denominated in Toman, and the result shape depends on the parameter combination. It does not discuss pagination/truncation beyond the limit parameter or how often the list refreshes, which keeps it short of a 5.

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 verb and resource, then three compact clauses mapping parameter combinations to output shape, then the currency, then the cross-tool routing. The telegraphic fragments ('Brand only: one summary line per model') are dense but readable, and nothing is redundant with the schema beyond mild overlap on the year-requires-model rule.

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 return-shape burden and does so for each of the three calling modes, plus currency and the ID fields needed for chaining into hm_price_estimate and hm_search_cars. Residual gaps are minor: no mention of what happens with an invalid brand slug or how truncated results at the default limit of 60 are signalled.

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 goes past the per-field docs by explaining the combination semantics (brand alone = per-model summary; model adds trims/years; year requires model) and by naming where the slug values come from. The only unstated interaction is how limit behaves in the brand-summary mode versus the trim mode.

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 today's market (used and zero-km) prices of cars') plus the data source ('Hamrah Mechanic's daily price list'), which immediately separates it from siblings like hm_price_history or hm_price_estimate. The following sentences enumerate exactly how the result narrows with each parameter, so an agent can predict the output without opening the 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?

Gives clear operative guidance: brand-only for a summary line per model, brand+model for trim/year prices, brand+model+year for one year's trims, and it names the prerequisite sources ('use brand slugs from hm_brands'). It also routes onward explicitly ('take a type_id ... to call hm_price_estimate, or the model slug to call hm_search_cars for real ads'). What is missing is a direct statement of when NOT to use it, e.g. versus hm_price_list or hm_price_history, which are never mentioned.

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