gold_etsy_fulfill_order_tracking

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

With no annotations, the description carries the behavioral burden. It discloses that this performs real fulfillment (a state-changing, non-mock operation) and requires the user's own API key and paid plan. However, it does not describe side effects, reversibility, or return behavior, leaving some ambiguity.

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?

Three short, front-loaded segments convey the core action, the non-mock warning, and the BYOK/paid prerequisites with minimal waste. The fragmented style is slightly abrupt, but every element earns its place.

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 5-parameter mutation with no annotations or output schema, the description is thin, but the schema fills key gaps: confirm gate, date_shipped default, and carrier examples. The main missing piece is the relationship to receipt_ids from other Etsy tools and the optionality of carrier_name, which could lead an agent to over-require inputs.

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 already describes confirm, carrier_name, and date_shipped (60% coverage); the description adds that tracking_code and carrier are the key upload payload, tying them to 'Mark an order shipped.' It does not clarify receipt_id format or that carrier_name is optional despite the description implying both are uploaded.

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 action ('Mark an order shipped') and the target resource (a receipt), with concrete inputs (tracking code + carrier). The phrase 'real fulfillment, not a mock' distinguishes it from test/dry-run flows, and none of the sibling tools cover order fulfillment, so it stands apart clearly.

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?

Provides clear invocation context: use for real fulfillment, not mocks, and only with BYOK and a paid Pro plan. It does not name alternatives, but none of the listed siblings perform fulfillment, so the exclusionary guidance is sufficient.

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