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

The description discloses critical behavioral traits beyond the annotations: the two-phase send-on-confirm design, fixed recipient, and the guarantee that it does not write order/customer data. This goes well beyond the bare-annotations safety profile and prevents accidental sends.

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 structured and front-loaded, with each sentence serving a distinct purpose: purpose, process, constraints, content guidance, and delivery outcome. No wasted words despite covering a multi-step tool.

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 tool with no output schema and 10 parameters, the description covers purpose, the preview vs. send distinction, what to include, the fixed recipient, non-effects on orders/charges/data, and how the buyer is contacted. This is unusually complete for a complex 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?

All 10 parameters already have schema descriptions, so the baseline is 3. The description adds value by instructing agents to populate part numbers, sensor, quantity, and application when known, and explains the confirm flag's role in the preview/send sequence beyond its schema default, meriting a 4.

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 'Forward a buyer request-for-quote or engineering question to the Commonlands engineering team,' using the specific verb 'forward' and naming the exact resource and destination. This clearly distinguishes it from sibling tools like create_cart or get_catalog_snapshot_status, which handle commerce or catalog queries.

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 explicitly states the two-step preview/confirm workflow ('the first call returns a preview and sends nothing... call again with confirm: true to send'), provides when advice ('Include part numbers, sensor, quantity, and application when known'), and clarifies exclusions ('never creates an order, charges a card, or writes Shopify/customer data'), implicitly steering agents away from commerce tools.

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