firestarter_save_ship_from

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

Annotations provide readOnlyHint: false, so the description correctly implies mutation. The description adds meaningful behavioral context beyond annotations: the three-form behavior, the primary-origin semantics ('the primary drives every quote's origin'), and the country-specific requirements. It doesn't address edge cases like what happens on overwrite or partial failures, but for an idempotent-looking save operation, this is solid. Minor deduction: it doesn't warn about potential side effects like changing the origin for existing quotes, but the primary emphasis mitigates that.

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 dense but efficient. It front-loads the core purpose, then packs the three operational forms into three parenthetical clauses, then adds the primary key insight. Every sentence adds information; no filler. The structure mirrors the decision an agent must make (create vs update vs promote) in the same order, making it easy to parse.

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 10 parameters, full schema coverage, no output schema, and a sibling list that includes firestarter_delete_ship_from and firestarter_ship_from_locations, this description covers the essentials. It explains the three forms, primary semantics, and restrictions. It could note that the response is likely the saved location or an error, but without an output schema, that's a minor gap. It also doesn't mention authorization beyond 'Seller accounts only' — but that's a small omission.

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 100%, so each of the 10 parameters is already documented in the schema. The description adds cross-parameter relationships (e.g., street1 + city required when creating, state/zip required for US/CA/AU, location_id or omit to create) that the individual schema descriptions lack. It also clarifies the role of is_primary ('Set is_primary on the address parcels actually dispatch from — the primary drives every quote's origin.'). This exceeds the baseline 3 for full coverage by explaining interaction between parameters and conditional requirements.

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: 'Add or update a seller ship-from (fulfillment) location — the address shipping rates are quoted FROM.' It uses a specific verb-resource pair and immediately distinguishes the ship-from tool from its sibling firestarter_save_address (which likely handles buyer/seller addresses) and firestarter_ship_from_locations (a read/list tool). The three operational forms enumerate exactly what the tool does, leaving no ambiguity about create vs update vs promote-to-primary.

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 explicitly breaks down three usage forms with clear conditions: (1) no location_id → create, (2) location_id + address fields → update, (3) location_id + is_primary true and no address fields → promote. It also states the requirement for US/CA/AU origins (state/zip required) and the seller-only restriction. This is more than enough for an agent to decide when to invoke and how to structure arguments.

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