freight_parse_bol_pod

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

With no annotations provided, the description carries the burden of behavioral disclosure. It does add useful context by disclosing the $0.15 USDC cost per call, which is significant operational information. However, it does not explain behavior around missing/empty inputs, which combination of parameters to use, potential errors, or the exact structure of the returned JSON, 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?

The description is a single, tight sentence that communicates the tool's purpose and a critical business detail (cost) without any filler. Every word earns its place and the key action word 'Parse' is front-loaded.

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?

The tool has four optional parameters and no output schema, so the description is the only source of context for expected output and invocation. It says output is 'structured JSON' but does not clarify which parameters are typical (e.g., text vs file_path vs pdf_base64), default behavior of 'mode', or what happens on failure. The sibling list provides document-type context, but the description alone leaves moderate gaps for a paid 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 100%, so each of the four parameters (mode, text, file_path, pdf_base64) is already explained in the input schema. The description adds no parameter-level details beyond noting PDF or text inputs, so the baseline score of 3 is appropriate given the schema does the heavy lifting.

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 opens with a specific verb 'Parse' and names the exact resource type ('Bill of Lading / Proof of Delivery'), making it clear what document this tool handles. It also distinguishes itself from sibling parse tools like freight_parse_fuel_receipt or freight_parse_w9 by document type. The mention of 'PDF or text' and 'structured JSON' gives a precise scope.

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 clearly implies this tool is for Bills of Lading and Proofs of Delivery, which helps an agent choose among the document-specific sibling parse tools. However, it does not explicitly say when not to use it or mention alternatives such as freight_parse_fuel_receipt for other document types, so it stops short of a 5.

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