ebay_create_fulfillment_policy

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

The description discloses the exact error text, explains the confusing DomesticItemShippingService[0]/[1] citation as remote validation rather than client duplication, warns that the sandbox accepts a smaller code set, and states the required OAuth scope. These details go well beyond the sparse readOnlyHint=false annotation.

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 long but dense and front-loaded, with the purpose stated first and the most error-prone constraint explained next. The known-good payload sketch is compact and useful, though the OAuth scope is stated twice in slightly different forms, which is a minor 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?

For a deeply nested create call with no output schema, the description provides a near-runnable payload template, validation semantics, environment caveats, and authentication requirements, covering most practical invocation needs. It stops short of describing the success response or duplicate-policy behavior, so it is not fully complete.

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 0% schema description coverage, the description compensates with a concrete known-good EBAY_US FLAT_RATE policy sketch and explicit guidance that shippingServiceCode must be a valid enum, not an invented code. However, many nested fields such as localPickup, shipToLocations, rateTableId, and freightShipping receive no explanation, so coverage is strong but not exhaustive.

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 opening sentence states a specific verb and resource: 'Create a new fulfillment policy.' The rest of the description reinforces this by focusing on creation payloads and validation for that exact operation, making its role clear even among many ebay_create_* relatives.

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 implies the create use case and provides actionable preconditions such as OAuth scope and valid shippingServiceCode values, but it never explicitly tells the agent when to prefer this tool over ebay_update_fulfillment_policy, ebay_get_fulfillment_policy, or ebay_create_return_policy. Usage context is clear but alternatives/exclusions are not stated.

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