marketplace_listing

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

Annotations already establish readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds real behavioral value: photos are returned as actual images only when include_photos is set, and it flags why that matters (verifying the item matches the title, detecting stock photos or damage).

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 dense sentences, no filler. The returned-field list is front-loaded and the actionable advice about include_photos follows immediately, so the agent gets the important guidance without scrolling.

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 compensates by enumerating the main returned fields and explaining photo behavior. Minor gaps remain (no mention of error/not-found behavior or cost of requesting six images), but for a single-item read tool this is close to complete.

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 goes further by explaining the intent behind include_photos ('to SEE the real photos') rather than just restating that it controls image count, which meaningfully guides the agent to set it above the default 0.

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 precise verb+resource ('Full detail for one listing') and enumerates exactly what the payload contains: description, condition, pickup area, delivery options, photos. This clearly separates it from sibling lookup tools like marketplace_search or marketplace_compare, which operate over many listings.

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 a genuine when-to-use for include_photos ('to SEE the real photos... spot stock photos, damage, serial numbers'), which implies pre-purchase inspection. However, it never says when to prefer this tool over marketplace_search, marketplace_compare, or marketplace_price_history, so alternative selection 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.