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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the returned fields, the expansion triggered by include_profiles, and the 20-profile ceiling per run. It stops short of disclosing cost or credit consumption, which lives only in the max_charge_usd parameter description.

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?

Four sentences, front-loaded with purpose and return shape, with no wasted phrasing. The 'matches company names, not products' caveat is valuable but sits after the include_profiles sentence, which slightly interrupts the flow from search behavior to output options.

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?

With nine parameters, no output schema, and no siblings, the description carries real weight and it does cover return values, the search matching rule, and the profile expansion cap. It leaves the company_urls full-read mode and the charge-limiting behavior to the schema, which is a minor gap for a tool with this much surface area.

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 coverage is 100%, so all nine parameters are already documented in the schema, setting the baseline at 3. The description reinforces two of them (search term semantics and include_profiles expansion) but adds no syntax, format, or default information beyond what the schema already states.

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 definition names a specific verb and resource, 'Search US customs bill of lading records by company name,' and states the result shape, 'shipment counts and last shipment dates.' An agent knows exactly what data it retrieves and the importers/suppliers dual scope is clear from the description plus the mode enum.

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?

It gives a clear use context and one explicit exclusion: 'The search matches company names, not products,' plus 'Set include_profiles to add...' which tells the agent when to turn that flag on. There are no sibling tools to route between, so the only missing piece is guidance on when this tool is not appropriate at all.

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