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

Annotations already establish readOnly=false, destructive=false and openWorld=false, but the description adds substantive behavioral context: the uniqueness constraint on name, the dependency that contactEmail is required for send_purchase_order to function, and the consequence that a new supplier carries no items and cannot be ordered from yet. These are non-obvious mutation semantics that annotations do not convey.

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?

Purpose is front-loaded in the first clause, and each subsequent sentence delivers actionable information (uniqueness, contactEmail dependency, item-linking prerequisite, data-integrity warning). It is slightly dense with four distinct instructions, but no sentence is filler.

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 an 11-parameter mutation with no output schema and partial schema coverage, the description covers the essential creation constraints, the key optional field's purpose, and the downstream workflow. It omits any note on the return value, though for a create tool with sibling getters that is a minor gap.

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 73%, so the baseline is 3, but the description adds meaning the schema lacks: it clarifies that only name is required, that name must be unique, and crucially explains what contactEmail is actually for (the destination for emailed purchase orders). The remaining 9 optional address/contact fields are left to the schema.

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 a specific verb+resource: 'Add a business the merchant buys from', which unambiguously identifies a supplier-creation tool. It distinguishes itself from siblings like hub_update_supplier and hub_delete_supplier by describing creation, and references the downstream workflow (link_supplier_items, send_purchase_order) that only applies to new suppliers.

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?

Explicitly states when to set contactEmail ('if the merchant will ever email purchase orders'), the required prerequisite (name, unique among company suppliers), and the workflow ordering constraint (link items before creating a purchase order). It also instructs the agent to ask the merchant rather than invent details, covering a real edge case.

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