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

Goes well beyond the annotations: discloses the privacy treatment of coordinates (kept only as a coarse area, never stored exactly), that no email is collected and there is no follow-up, and a per-caller-per-day rate limit. It also explains what the returned status values mean and that neither promises coverage, and constrains how the agent may relay `message`. Nothing here contradicts the write-oriented annotations (readOnlyHint=false).

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?

Purpose and privacy posture are front-loaded, and every clause carries information (privacy, consent, rate limit, status meaning, message handling). It is dense with semicolon-chained clauses, which costs some scannability, but there is no 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?

With no output schema and three undocumented parameters, the description still covers what the agent needs: when to call, what to send, what comes back (accepted/queued plus message semantics), privacy implications, and the rate limit. Nothing material to a correct invocation or correct shopper-facing response 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 0%, so the description must carry the load, and it does: lat/lng are explicitly optional ('if known') and are described as reduced to a coarse area, and category is named as the primary payload. It adds no format or granularity guidance for category beyond the schema's maxLength, so it stops short of full coverage.

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 ('Records that a shopper wants a shop category near a place') plus the intent ('so Onhand can see where to add listings'), which cleanly separates it from the search/discovery siblings like find_business and discover_local. An agent can tell this is a demand-capture write, not a lookup, 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 a clear operating condition ('Ask the shopper before calling') and frames the situation in which it applies (a shopper wants a category near a place). It does not explicitly name a fallback such as discover_local when the category already exists, so routing versus alternatives is left partly to inference.

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