Create Company Vendor

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

The description adds valuable behavioral context beyond annotations: it states that calling again creates another record (non-idempotent), returns HTTP 201 with new id, and describes common error codes (401, 403, 404). Annotations already indicate readOnly=false and idempotentHint=false, but the description enriches this with specific response and error behavior.

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 moderately long but well-structured with a heading for country codes and clear enumeration of response/error behavior. Each sentence provides useful information: purpose, code constraints, non-idempotency, error statuses, required params, and API endpoint. No wasted words.

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 create tool with an open-world nested object and no output schema, the description is thorough. It explains the return value (HTTP 201 with new id), non-idempotent behavior, common error scenarios, country code standards, and the API endpoint. This provides sufficient context for an agent to invoke the tool correctly.

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%, but the description adds meaning beyond the schema by highlighting that country_code and state_code must conform to ISO-3166 Alpha-2, and that these are nested within the vendor object. It also explicitly lists the required parameters (company_id, vendor), reinforcing schema information.

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 clearly states the action: 'Create a new Vendor associated with a specified Company.' It distinguishes from sibling tools like create_project_vendor by explicitly scoping to Company. It also specifies required parameters and the API endpoint, making the tool's purpose unambiguous.

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 provides clear context for when to use this tool: creating a company-level vendor. It does not explicitly mention alternatives (e.g., create_project_vendor) or exclusion criteria, but the 'Company' scope is clearly implied. The API reference and required parameters reinforce appropriate usage.

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