fba_analyze

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

With no annotations, the description carries the full burden and does so: it discloses the default detail level and what each level returns (summary returns a caveats list; full adds thresholds, all suggestions, assumptions), instructs the agent to quote `summary` as one self-contained paragraph, flags provenance limits ('third-party-compiled rules', 'Amazon's own measurement governs'), and explains how ambiguous unit inputs are interpreted and echoed back.

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?

Front-loads the value proposition and return content before the input contract, and the density is largely justified by 15 parameters at zero schema coverage. It is nonetheless a long block with some terse shorthand that an agent must parse carefully, so it stops short of ideal crispness.

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?

An output schema exists so return values need not be re-specified, yet the description still tells the agent which field to quote and how detail level changes the payload. Combined with the v0.1 class limitation, the fee-provenance caveat, and near-total parameter coverage, an agent has everything needed to call and interpret this tool.

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%, so the description must compensate, and it does for nearly every parameter: dims accepts three formats with an example, weight accepts numbers or unit-suffixed strings with a default-units rule, and it documents dims_unit, weight_unit, dims_sigma, weight_sigma_oz, ship_date, margin_in, margin_pct, max_shrink_pct, min_dims, and detail (with default). Only include_fuel_surcharge and units_per_month are left unstated.

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?

Opens with an explicit routing statement ('START HERE for "what FBA tier and fee is this product?"') and enumerates exactly what one call returns: size tier, dimensional/shipping weight, fulfillment fee, nearest limit with margin, risk class, and best shrink cut. It also names the sibling tools (fba_tier_headroom / fba_size_tier / fba_fee_estimate) and scopes them as detail-only alternatives, so the agent can distinguish it without opening any schema.

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?

States when to use it ('START HERE'), when to prefer the alternatives ('Use fba_tier_headroom / fba_size_tier / fba_fee_estimate only when you need that detail'), and adds a scope limit ('Only product_class "standard" is modelled in v0.1'). This is explicit use/alternative/exclusion guidance.

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