Get one used-car ad

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

Beyond the readOnly/idempotent annotations, the description discloses real data-availability constraints: the full inspection report requires a Karnameh login, so only date, link and a one-line verdict are returned, and seller phone numbers are unavailable. These are exactly the gaps that would otherwise cause an agent to promise data the tool cannot deliver.

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 short sentences, front-loaded with what is returned, then when to use it, then the data limitations. No redundant restatement of the name 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?

With no output schema, the description carries the burden of describing return contents and does so field by field, plus flags the login-gated inspection report. Nothing needed to call this correctly on a single required UUID parameter 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 the schema itself explains that id is the UUID taken from kn_cars, including a format example. The description adds nothing beyond that, so the baseline of 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 and resource ("Get one Karnameh used-car ad") and enumerates the payload (price, specs, seller description, strengths, inspection summary). It also contrasts with the sibling kn_cars, so an agent can distinguish single-ad retrieval from list retrieval without inspecting either 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?

"Use after kn_cars to read an ad in full" gives clear sequencing and names the alternative tool that supplies the required id. It stops short of an explicit when-not or error guidance, but the usage context is unambiguous.

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