create_fulfillment_plan

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

Annotations are missing, so the description carries the full weight. It hints at immutability ('immutable plan result') which implies the plan cannot be modified post-creation, a key behavioral trait. However, it does not disclose whether the action is destructive (overwrites existing allocations), requires authentication/authorization, or has rate limits. A 3 reflects partial disclosure but missing critical behavioral details for a mutation tool.

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 a single, concise sentence of only 8 words, with no redundant phrases. Every word ('allocate', 'physical copy', 'once', 'immutable', 'plan result') serves a purpose. It fits the tool's likely complexity and is front-loaded with the action and key constraint ('immutable').

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 has a complex structure (nested object with 3 fields), no annotations, no output schema explanation (though output schema exists, context signals say 'has output schema: true', but description doesn't leverage it), the description is insufficient. It covers the core purpose but omits parameter details, error scenarios, and return values. The completeness is adequate for a simple tool but gaps remain for the nested input schema.

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% (context signals), so the description must compensate entirely. The description does not elaborate on the parameters (resolution_id, mode, exact_target_id). However, because there is only one parameter (request) that is an object with nested fields, and the description is minimal, it cannot adequately explain their semantics. Average baseline is 3, but given the very low coverage, a 4 would require description to fully cover parameters. Here it fails, but schema has no descriptions at all, so 4 is too generous. Actually, since coverage is 0% and description doesn't clarify params, score should be 2.

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 'Allocate each physical copy once inside an immutable plan result' clearly identifies the verb (Allocate) and resource (physical copy within an immutable plan result), distinguishing it from sibling tools like 'search_cards' or 'compare_decks'. It specifies a unique action ('allocate') and context ('immutable plan'), making the purpose unambiguous.

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 provides no guidance on when to use this tool versus alternatives like 'resolve_availability' or 'plan_deck'. It does not mention any prerequisites (e.g., a plan must exist), exclusions (e.g., cannot modify after allocation), or conditions (e.g., requires permissions). Context signals show sibling tools share similar domains (planning/resolving), making such guidance critical.

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