list_vendors

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

With no annotations present, the description carries the full behavioral disclosure burden. It discloses that data is live, that the response contains sensitive PII and financial fields (birth_date, identification_number, ACH details), and that trade categories/service areas are not exposed by the API. This is meaningful transparency beyond the schema, though it does not mention pagination or rate limits.

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?

Every sentence earns its place: the lead sentence states the core action, the next summarizes the return fields, the third gives concrete use cases, and the final sentence warns about data sensitivity. The description is long but densely informative known, with the main purpose front-loaded.

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?

With zero parameters and no output schema, the description carries the full burden of informing the agent. It compensates by enumerating the major field categories, noting live data, listing realistic use cases, calling out a known API limitation (no trade categories/service areas), and warning about PII and financial sensitivity. There is no missing information needed to invoke or interpret the tool's result.

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?

The tool has zero parametersaren an empty schema, and schema description coverage is 100%, so there are no parameter semantics for the description to clarify. The baseline for 0-param tools is 4, and the description appropriately focuses on the return payload rather than inputs.

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 a specific action and resource: 'List all vendors from Rentvine (live data).' It clearly distinguishes this list tool from a single-record getter by saying it returns every field the /vendors/search endpoint exposes, and it names recognizable vendor fields. The purpose is unambiguous even without opening the schema.

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 explicitly states when to use the tool: 'Use to find vendors for work-order assignment, bill creation, or compliance review.' It does not explicitly say when not to use it or compare it against the sibling get_vendor tool, but the use cases and 'all vendors' scope imply the distinction. A brief exclusion note would make it fully comprehensive.

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