Plan Pickup

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

With no annotations present the description carries the full burden and does so well: it discloses that apply=True builds (replaces) baskets in each stop's market ready for reservation, what all_at_primary_market means in the result, that stock is real per market, and how primary/fallback defaults are derived (selected market vs T00MY_HOME_MARKETS). The replace semantics are the key mutation risk and they are stated.

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?

Core purpose is front-loaded in the first sentence, then the algorithm and defaults follow in a logical order. It is dense and somewhat long, but nearly every sentence carries operational information; only the bulky-examples parenthetical is expendable.

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 six-parameter, zero-coverage, no-annotation tool with a mutation path, the description covers the workflow, defaults and result flag in enough depth to invoke correctly. Gaps remain around from_market and the items element format, which an agent must guess from the schema alone.

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 compensate and it only partly does: apply, bulky_skus, primary_market and fallback_markets are explained or have their defaults described. However items is only gestured at ("a list of articles") with no object shape, and from_market is never explained at all, leaving two of six parameters opaque.

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 (plan where to pick up a list of articles / the current basket) and immediately frames the strategy (primary market first, fallbacks second), which cleanly separates it from siblings like find_markets, compare_markets and markets_nearby. An agent can tell what this does 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 clear operational context: priority rules (1/2), when a fallback is eligible (only if small enough to transport without the special vehicle), how to flag bulky items, and how defaults are resolved. It never names an alternative tool or says when NOT to use this, so it falls short of explicit routing guidance.

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