update_vendor

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

No annotations are provided, so the description carries full burden of behavioral disclosure. It does mention that 'active' deactivates/reactivates and notes clearing behavior via empty string, but it doesn't disclose whether changes are reversible, what happens to unmentioned fields (presumably preserved), whether id lookup fails loudly, or what the response is. For a mutation tool with zero annotation coverage, this is a significant gap.

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?

Effectively front-loaded: the tool purpose appears in the first line, followed by a compact args list. Every line earns its place. The reference to update_customer is efficient but slightly lazy. Slightly verbose with the blank lines and 'Args:' label, but overall clean and readable.

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?

This is a mutation tool with no annotations and an output schema present. The description covers each of the 6 parameters at least minimally. However, it's a write operation with 6 parameters, no annotation coverage, and heavy reliance on a sibling tool's documentation for the address structure. For a mutation tool of this complexity, it should state prerequisites (vendor existence), idempotence, or error behavior. Adequate but leaves meaningful gaps.

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 17%, so the description must compensate. It does describe each parameter concisely (id, name, currency, notes, active, address). The notes and active semantics are useful and go beyond schema. However, it relies on external reference for 'address' details, and the schema itself provides some structure. The description adds moderate value but doesn't fully cover the 83% undocumented space.

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 'Update an existing vendor' with a specific verb and resource. It adds parameter semantics for each field. However, it relies heavily on referencing 'update_customer' for address details rather than fully standing alone, and doesn't distinguish this from update_employee (siblings exist for both). The purpose is clear but sibling differentiation is minimal.

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?

There is no guidance on when to use this tool vs alternatives like create_vendor, delete_vendor, or update_customer. The reference 'Same semantics as update_customer' is helpful but doesn't establish when a user would choose update_vendor over other operations. No exclusions or prerequisites (e.g., vendor must exist) are stated.

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