logistics_verify_ebl

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

With no annotations, the description carries the full behavioral burden. It does disclose two non-obvious traits: the tool returns a cryptographic hash, and it has a paid two-tier pricing model tied to a Security-Gate-x402 signature. It does not say what happens on verification failure, whether it is read-only, whether external carriers/AIS providers are queried, or what error shape to expect.

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 dense sentences, front-loaded with the verification targets, then the output, then cost. No filler. The pricing clause is long but is materially useful information an agent must know before invoking.

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 six-required-parameter, no-annotation, no-output-schema tool, the description covers the output hash and the cost model but omits failure/negative-result behavior, which matters for a verification tool. Adequate but with clear gaps an agent would want filled.

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% with all six parameters documented with examples (e.g. MAEU123456789, KRPUS, 9876543), so the baseline is 3. The description adds no parameter-level detail beyond the schema, offering no format rules or cross-field constraints.

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 states a specific verb (Verifies) applied to three concrete resources with named standards: DCSA eBL v3.0, ISO 6346 container numbers, and AIS vessel IMO tracking. It also names the concrete output (blDocumentHash). It does not differentiate itself from siblings like logistics_audit_telemetry or logistics_issue_pod_attestation, so it falls short of a 5.

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?

Usage is only implied: 'for on-chain escrow creation' hints at when the hash is needed, and the dual pricing tier signals a payment-signature path. There is no explicit when-to-use, when-not-to-use, or named alternative among the many verify_*/audit_* siblings.

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