deliveries_retrieve__get_deliveries_by_delivery_date_and_phone

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to restate safety. It adds valuable context about the 7-day data availability guarantee and the throttling constraint (10 req/60s), which are not in the annotations. However, it doesn't mention response size, pagination behavior, or rate limit specifics beyond the basic guidance, so it adds some but not rich behavioral context beyond what annotations already cover.

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 concise (about 3 sentences) and front-loads the key purpose and scoping constraint. The instruction to get IDs and the throttling note are useful, but the throttling detail is somewhat buried at the end. Overall, it's efficient with no fluff, but the parameter guidance is missing, which the conciseness cannot fully compensate for.

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?

Given the tool's complexity (many optional parameters, no output schema, no schema descriptions for parameters), the description is incomplete. It lacks guidance on how to use the filter parameters effectively, what date formats to use, the meaning of startRevision, and the impact of rowsCount/sourceKeys. The annotation says read-only, so the destructive risks are covered, but the operational details are missing. An agent would struggle to correctly fill the request object without additional knowledge.

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%, meaning the schema provides no descriptions for individual parameters (only the request wrapper is described). The description mentions phone, dates, and revision but does not explain the full set of parameters (rowsCount, sourceKeys, startRevision, deliveryDateTo). For a tool with many optional parameters and zero schema descriptions, the description should compensate by explaining key parameters and their formats (e.g., date format, UUID for organizationIds). This is a significant gap.

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 clearly states the tool retrieves orders by phone number and date range, and mentions 'revision' as a secondary search mode, distinguishing it from sibling tools like get_delivery_by_id and get_deliveries_by_delivery_date_and_status. It also provides a critical scoping detail: the guarantee is only for the last 7 days, which clarifies the tool's core purpose.

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 explicitly tells where to get organization IDs (via organizations__get_organizations), which is essential for effective use. It also notes the throttling limit and advises caching, which guides usage behavior. However, it does not explicitly contrast with sibling tools like get_delivery_history_by_date_and_phone for older data, though the schema's deliveryDateFrom description hints at that alternative. The where-to-get-ID guidance is a strong use-case clarification.

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