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

Annotations declare readOnlyHint=true and destructiveHint=false, so the safety profile is already covered. The description adds valuable behavioral context: it returns merchant-synced price, inStock, imageUrls, sku, description, catalogSyncedAt, priceSource (feed|live), always includes attributed url, trackedUrl, and pick. It also discloses the auth behavior (sessionId required for live data, never invent sessionId) and the rule about using trackedUrl instead of url. This goes beyond the annotations without contradicting them.

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?

The description is dense but every sentence earns its place. It front-loads the core purpose, then covers auth, return fields, link usage, and triggers. It is longer than average, but the length is justified by the auth complexity and the critical trackedUrl rule. A slight trim could improve scannability, but the structure is logical: purpose → auth → returns → usage rules → triggers.

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 product lookup with no output schema, the description covers everything an agent needs: what it returns, when to call it, how to handle auth, what to do with the returned trackedUrl, and trigger phrases. The absence of an output schema is compensated by the explicit return field list. The description is complete for the tool's complexity.

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 50%: product_id and store_id have no descriptions in the schema, while q and sessionId do. The description compensates by explaining product_id + store_id as the composite key for a ProductCard, and explains q as 'the owner's search phrase so pick explains this sku against that query.' It also explains sessionId's role in the agent-link auth flow. The description adds meaning beyond the schema for the undocumented parameters, though it doesn't give format details for product_id/store_id.

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 states a specific verb and resource: 'Get one ProductCard by product_id + store_id from an allowlisted store.' It clearly distinguishes this from sibling search_products (which searches) and list_allowed_stores (which lists stores). The scope is precise: one product, identified by two keys, from an allowlisted store.

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 explicit when-to-use guidance: call to confirm price and stock before create_purchase, never quote price from memory. It also gives when-not-to-use guidance: never web-search, never begin_agent_link again if sessionId already exists, never ask the owner to edit connector settings. It names the alternative flow (begin_agent_link → poll_agent_link) for live data. This is exemplary usage guidance.

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