distributor_fulfillment_options

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly covers read-only semantics, the meaning of three-valued fields (null as 'not determined' with specific reasons), the interpretation of null as a hold, candidate flags (not_carried, blocked, stale), and money handling (unit_landed is per-unit goods-only, shipping null until order placed). It even warns against common pitfalls like misinterpreting null or ranking as permission. This is exemplary transparency.

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 well-structured with clear sections (three-valued fields, candidate flags, money) and is front-loaded with the core purpose. While lengthy, every sentence adds value—it explains complex semantics and warns against common misinterpretations, making the length justified. No filler or redundancy.

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?

The description is complete for a tool of this complexity. It covers input context (one web order), output semantics (verdict, flags, money), critical null behavior, and pitfalls. Even though there is no output schema, the description fully explains what the agent will receive and how to interpret it, leaving no gaps for correct invocation and interpretation.

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?

The only parameter 'woo_online_order' is not explained in the description beyond the schema's bare type (string). Schema coverage is 0%, and the description only implies the parameter identifies the web order ('ONE web order') without specifying the expected format (e.g., an ID) or any constraints. Since there's only one parameter, the description could easily compensate, but it doesn't, leaving the agent to infer meaning.

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's purpose with a specific verb ('decide how to fill ONE web order') and resource (web order), and lists the outputs (per-line distributor candidates, local stock comparison, verdict). It immediately differentiates itself from ordering tools by stating 'Read-only — it plans nothing and orders nothing', making it easy to distinguish from siblings like distributor_quote or distributor_orders.

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?

It gives clear context (for exactly one web order) and establishes that it is read-only, implying it should not be used for planning or ordering. However, it does not explicitly name alternative tools or state when another tool should be used instead (e.g., distributor_quote for pricing or distributor_orders for placing orders). The guidance is implied rather than explicit.

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