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

Annotations already mark the tool readOnly and non-destructive, and the description adds substantial behavioral context: it enumerates return fields, prohibits substituting nearby pharmacies for exactPharmacy queries, requires explicit stock-risk warnings, explains two-stage deliveryPreview reporting, and specifies that all listed brands are valid partner pickup points. It also discloses the NEED_PICKUP_LANDMARK behavior and the canPromiseFinalDelivery guardrail, going far beyond what annotations convey.

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 front-loaded with purpose and trigger conditions, and nearly every sentence carries a useful rule. However, it is a dense wall of Always/Never directives without sectioning or formatting, so it is less crisp than ideal. The length is largely justified by the tool's complexity, but the structure could be improved.

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 must carry return-value and conditional-behavior information; it does, listing fields like distanceBasis, nearbyIncompleteOptions, missingItems, inStock, lowStockItems, distanceAssessment, and deliveryPreview. It also covers failure cases (matched=false, NEED_PICKUP_LANDMARK), authentication fallback via sessionId, stock warning thresholds, and the required handoff step, making the tool callable without major gaps.

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?

With schema description coverage at 63%, the description carries meaningful parameter burden. It explains why items should include product names ('so missingItems are human-readable'), what near must contain ('at least city + metro/street/district' with an example), when exactPharmacy should be true, and how lat/lon or sessionId can be used. This adds real semantic value beyond the raw schema fields.

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 opens with a specific role: 'Ozerki pickup-point resolver for multi-brand Ozerki-network pharmacies.' It immediately states the exact trigger ('MUST be called before handoff when the owner asks for pickup near a place or has no exact delivery address') and distinguishes the tool from the handoff step by saying the chosen storeId is passed to prepare_ozerki_handoff. An agent can tell exactly what this tool is for.

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 very explicit when-to-use conditions and important exclusions: a city name alone selects only a region and must not be treated as a location; if neither landmark nor coordinates are known, ask one short question; exact-pharmacy questions require exactPharmacy=true and must not substitute another branch. It does not, however, explicitly name sibling tools as alternatives (e.g., search_products) when deciding between catalog search and pickup resolution, so it falls just short of perfect routing guidance.

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