netsuite_create_vendor

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

With no annotations, the description discloses important behavioral traits: the 400 failure retry mechanism, the requirement for customForm/customFields in some cases, and externalId for idempotency. It does not mention response format or permissions, but the core mutation behavior is clear from 'Create'.

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 paragraph but logically structured: purpose, error handling, then required/optional lists. It is information-dense with no fluff, though a bulleted list might improve readability. Every sentence provides value.

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?

Given 15 parameters, low schema coverage, and no output schema, the description covers the main hazard (customForm) and idempotency, but omits format expectations for subsidiary, currency, country, and address fields. It also does not state what the tool returns (e.g., vendor ID). These are meaningful gaps for an agent to use it 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 description coverage is only 13%, so the description compensates by explaining key non-obvious parameters: externalId 'for idempotency', customForm 'string, custom form ID', customFields 'object, key-value map'. Other params are listed by name, which is acceptable for self-explanatory fields, but formats like subsidiary ID vs name are not clarified.

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 'Create a new NetSuite vendor (supplier)', providing a specific verb and resource. This clearly distinguishes it from sibling tools like netsuite_update_vendor and netsuite_get_vendors, and the synonym 'supplier' reinforces the intent.

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 gives explicit conditional guidance: 'If vendor creation fails with 400, first call netsuite_get_vendor_forms to discover the correct customForm ID, then retry'. It also lists required vs optional parameters. However, it does not state when not to use this tool or contrast with other create tools, but the error-recovery workflow is a strong guideline.

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