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

Annotations already cover the safety profile (readOnly, openWorld, non-destructive), so the description's job is to add context, and it does: it discloses the return shape (passages plus source URLs) which no output schema documents, and the word 'current' signals live retrieval rather than cached data. It omits rate limits and how many passages come back by default, which keeps it short of a 5.

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?

Two sentences, front-loaded with the purpose and the retrieval source, with zero padding. The semicolon-joined second clause is slightly compressed but still 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?

For a two-parameter read-only lookup with full schema coverage, the description supplies the essentials: retrieval source, return content, and an implicit instruction to ground answers in the passages. Nothing critical is missing apart from guidance on competing tools.

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 100%, including topK bounds and a note forbidding API keys or private customer data, so the schema carries the parameter burden. The description adds no syntax, format or default guidance beyond that, making the baseline 3 correct.

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?

States a specific verb and resource ('Ask about current Vapi documentation') and adds what comes back ('documentation passages and source URLs'). It is clearly distinguishable from the assistant/call/simulation siblings, though it never mentions the potentially overlapping get_api_schema tool.

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 only usage instruction is 'use them to answer the question,' which concerns consuming the results rather than when to select this tool. There is no statement of when-not to use it and no routing to alternatives such as get_api_schema for raw API schema lookups.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure and supplies almost nothing. It doesn't say whether the assistant is immediately live, what defaults apply to llm/voice/transcriber when omitted, whether creation is reversible, or what identity/response is returned.

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?

A single six-word sentence with zero filler, but it is so terse that there is no structure to front-load anything useful. It earns no penalty for bloat, only for lacking substance.

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 create tool with 8 parameters, nested objects, and a required field, yet the description explains none of the creation semantics, defaults, or outcomes. Only the schema's parameter descriptions keep it usable at all.

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 100% and every one of the 8 parameters, including the nested llm/voice/transcriber objects and the firstMessageMode enum, is documented in the schema itself. The description adds no meaning beyond that, so the baseline of 3 applies.

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?

States a specific verb and resource ('Creates a new Vapi assistant'), so an agent knows this is a create operation for assistant entities. It doesn't explicitly differentiate itself from update_assistant or list_assistants beyond the verb, but the verb+resource pairing is 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?

There is no guidance on when to create versus update an existing assistant, no prerequisites, and no mention of what happens to unspecified configuration. The agent must infer usage entirely from the name.

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

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

No annotations are provided, so the description carries the full burden, and it delivers almost nothing. Beyond the word "outbound" it says nothing about immediate versus scheduled dialing, required configuration for the call to succeed, side effects, cost, or what identifies the created call; for a mutating, real-world-dialing tool this is a substantial 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?

It is a single short sentence with no waste, but it is under-specified rather than concise, and it contains a grammatical error ("a outbound"). Nothing beyond the tool name is 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?

The tool has five parameters (nested objects, a datetime constraint), zero required fields, no annotations, and no output schema. With no guidance on which parameters matter, what the response contains, or how scheduling interacts with immediate calls, the definition is not complete enough for confident invocation.

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 100%, so the schema already documents customer.number, assistantId, scheduledAt, phoneNumberId, and assistantOverrides. The description adds no meaning beyond the schema, so the baseline of 3 applies.

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?

"Creates a outbound call" names a specific verb (creates) and resource (call) and the direction (outbound), which distinguishes it from read-only siblings like list_calls and get_call. It does not, however, differentiate it from other creation tools (create_assistant, create_simulation) beyond the resource word.

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 when-to-use guidance, no prerequisites, and no mention of alternatives or conditions. An agent cannot tell from this text when to create a call directly versus scheduling one, nor what must be true (assistantId, phoneNumberId, number) before calling.

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

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

No annotations are supplied, so the description carries the full behavioral burden, and it discloses little beyond 'creates'. It does not say whether the new simulation's ID is returned, whether re-creating the same scenario/personality pair is allowed or errors as a duplicate, what permissions are needed, or whether the simulation is immediately runnable.

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?

Two short sentences, front-loaded with the core action and immediately followed by the next-step pointer. No filler or redundancy for a simple creation tool.

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 four-parameter mutation with no annotations and no output schema, the description is only partially sufficient: it names the action and the intended follow-up, but omits return value/ID, duplicate handling, and prerequisite lookups. Adequate but with clear gaps an agent would want filled.

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 100%, so the schema already documents all four parameters including name, path, and the two required UUIDs; baseline 3 applies. The pairing sentence adds a small conceptual gloss on why scenarioId and personalityId are both required, but no format or constraint detail beyond 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?

The description states a specific verb and resource ('Creates a simulation') and clarifies the domain meaning by defining a simulation as a scenario paired with a personality. It is clear on its own, though it does not explicitly differentiate itself from nearby siblings such as create_simulation_suite or create_simulation_personality.

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?

'Run it with run_simulations' gives a useful lifecycle pointer to the follow-up tool, which is real guidance. However, there is no statement of when to use this versus create_simulation_suite, and no mention that scenarioId/personalityId must first come from list_simulation_scenarios/list_simulation_personalities.

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

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

No annotations are provided, so the description carries the full behavioral burden. It says nothing beyond the bare fact of creation: no word on name-collision behavior, whether the referenced assistant must already exist, required permissions, or what the call returns.

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?

A single front-loaded sentence with zero padding; the definition of the resource follows immediately after the verb. Nothing here is wasted or restated from the schema.

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?

The tool takes a nested, additionalProperties-open assistant DTO validated against an external Vapi schema, has no annotations, and no output schema. For that complexity the description is thin: it never hints that the assistant argument is a full transient-assistant configuration, nor what a successful call produces or how the personality relates to a later simulation run.

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 100%, with name, path, and the nested assistant object all documented in the schema, so the baseline is 3. The description adds no parameter-level meaning beyond identifying that the personality acts as a simulated caller, which is contextual rather than semantic detail about the arguments.

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 uses a specific verb plus resource ("Creates a simulation personality") and then defines the concept inline as "the simulated caller that talks to the assistant under test," which an agent could not infer from the name alone. It stops short of differentiating this from close siblings such as create_simulation_scenario or create_simulation, so it is clear but not sibling-aware.

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 when-to-use guidance, no prerequisites, and no mention of alternatives. Given siblings like create_simulation_scenario and create_simulation, an agent gets no help deciding which creation tool to call when setting up a test.

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

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

No annotations exist, so the description carries the full behavioral burden, and it discloses almost nothing beyond creation. It does not state whether the scenario is immediately runnable, whether it is org/workspace scoped, what identifier is returned (no output schema exists), or how duplicates/names are handled.

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?

A single front-loaded sentence with no filler, defining the resource by its two core components. It is efficient, though the compactness comes at the cost of detail that would otherwise be valuable.

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?

The nested evaluations schema and 5-parameter shape are complex, and the very rich schema covers most field-level meaning, so the description is minimally adequate. However, with no annotations and no output schema, it should say what the caller gets back and how the new scenario is consumed downstream.

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 100%, so the schema already documents name, path, instructions, evaluations, and additionalFields in detail. The description adds only a light gloss that evaluations determine pass/fail, which is already implied by the evaluation fields' own 'required' and comparator semantics.

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?

States a specific verb and resource ('Creates a simulation scenario') and adds what the artifact contains: tester instructions plus pass/fail evaluations. It distinguishes the artifact conceptually from create_simulation or create_simulation_personality but never names those siblings explicitly.

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 versus create_simulation, create_simulation_suite, or create_simulation_personality. It also omits the typical workflow implication that a scenario must be referenced by a simulation before it can run, leaving the agent to infer prerequisites from sibling names alone.

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

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

With no annotations, the description carries the full behavioral burden, yet it says nothing about permissions, whether suite names must be unique, what happens on duplicate name or invalid simulationIds, or whether the operation is idempotent. It only explains the conceptual grouping effect, leaving all mutation-risk context to inference.

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?

A single well-formed sentence with the verb and resource front-loaded and zero filler. It is efficient, though the brevity is part of why coverage gaps exist elsewhere rather than a flaw in the prose itself.

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 straightforward create operation with a fully documented four-parameter schema, the description covers the what but not the return value (no output schema) or failure/duplicate behavior. Adequate as minimum viable, but a creation tool with no annotations should say more about what the caller gets back.

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 100%, so name, path, simulationIds, and additionalFields are already documented, including the folder-path pattern and GitOps mapping. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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?

States a specific verb and resource ("Creates a simulation suite") and adds the semantic effect — grouping simulations so they can be run together — which distinguishes it from sibling create_simulation and points toward run_simulations. It does not explicitly name those siblings, so differentiation is implicit rather than stated.

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?

Usage is only implied: the phrase "so they can be run together" hints that a suite exists to be executed as a batch, but the description never says when to create a suite versus individually creating simulations, nor does it reference run_simulations as the follow-up action. No prerequisites (e.g., simulations must already exist) or exclusions are given.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states that the tool creates a Vapi tool, without mentioning mutation effects, required type-specific fields, permissions, error behavior, or how the polymorphic type parameter controls valid configuration.

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 single sentence is concise and front-loaded, with no wasted wording. However, for an eight-parameter polymorphic creation tool, this level of brevity leaves the description under-specified rather than optimally structured.

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?

The tool has a complex schema with nested objects, multiple tool type variants, no annotations, and no output schema. The description does not explain the type variants, required type-dependent fields, or creation workflow, leaving significant context gaps for an agent.

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 high at 88%, so the schema already documents most parameters, including type-specific nested fields. The description adds no additional parameter meaning beyond the generic 'Vapi tool' framing, making the baseline 3 appropriate.

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 states a specific verb and resource: 'Creates a new Vapi tool.' This clearly distinguishes creation from sibling operations like update_tool, get_tool, and list_tools. However, it does not explain the polymorphic tool types or what kinds of tools can be created.

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 explicit guidance on when to use this tool versus update_tool or get_api_schema, nor any prerequisites or exclusions. The only implied usage is that it is for creation rather than update or retrieval.

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

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

With no annotations supplied, the description carries the burden and does real work: it discloses that cross-references are returned as "#/components/schemas/<Name>" placeholders and enumerated in referencedSchemas, which tells the agent how to follow up. It does not mention auth, rate limits, or whether search and name can be combined, but for a read-only reference lookup those gaps are modest.

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?

Three sentences, each earning its place: what it is, how to use the two parameters, and what the return shape implies for follow-up. The purpose is front-loaded with no redundant restatement of the name.

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 two-parameter read-only lookup with no output schema and no annotations, the description covers the source data, the call sequence, the return reference format, and the follow-up behavior. An agent has everything needed to call it correctly and interpret what it gets back.

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 100%, so both parameters are already documented including the "used when name is not given" precedence rule. The description's sequencing adds a little workflow context but no new semantics about the parameters themselves; baseline 3 is appropriate.

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 states a specific verb and resource ("looks up a schema in the Vapi API reference") and identifies the source of truth (the OpenAPI spec the SDKs are generated from). The final sentence about finding fields other tools accept through additionalFields makes its role distinct from the sibling documentation and CRUD tools.

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?

It gives a clear two-step workflow (use `search` to discover names, then `name` to fetch one) and a concrete use case, following referenced schemas when needed. It does not explicitly say when to prefer the sibling ask_vapi_docs instead, so the routing guidance is clear on this tool but not on its alternatives.

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

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

No annotations are supplied, so the description carries the full behavioral burden. "Gets" implies a read-only lookup, but it never states what happens when the ID is unknown (error vs. empty result), whether authentication or scope is required, or anything about the returned object.

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?

A single short sentence, front-loaded with the action and resource, with no filler. It is lean to the point of being under-specified, but nothing is wasted.

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 one-parameter lookup with no output schema, the core fact an agent needs (fetch a single assistant by its UUID) is present. Missing is any statement of return shape or not-found behavior, which matters more here because no annotations or output schema fill that 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 description coverage is 100%, with the single assistantId parameter fully documented including UUID format and pattern, so the baseline is 3. The phrase "by ID" in the description adds no syntax or format meaning beyond what the schema already provides.

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?

"Gets a Vapi assistant by ID" names a specific verb and resource, and "by ID" implies single-record retrieval, distinguishing it from list_assistants. It does not, however, explicitly differentiate itself from sibling getters such as get_call or get_tool.

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?

Usage is only implied: an agent can infer this is the tool for fetching one assistant when its ID is known, versus listing them. There is no explicit when-to-use statement, no mention of alternatives like list_assistants or ask_vapi_docs, and no prerequisites.

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

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

No annotations are supplied, so the description bears the full burden, yet it only says the tool gets details. It does not state that this is a read-only lookup, whether it errors on unknown or malformed IDs (the schema requires a UUID), or what object shape comes back.

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?

A single short sentence with no wasted wording and the resource front-loaded. Brevity here borders on under-specification rather than being padded, so it is efficient but thin.

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 one-parameter read tool with no output schema and no nested objects, little is required, but the ambiguous word "details" leaves the agent guessing what the response contains. Minimum viable rather than complete.

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 100% and callId is documented as "ID of the call to get", so the schema already covers the only parameter. The description adds no format, sourcing, or lookup-key guidance beyond that.

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?

"Gets details of a specific call" names a specific verb (gets) and resource (call) and implies single-record lookup, which an agent can distinguish from list_calls or create_call in the sibling set. It stops short of saying which details are returned or explicitly contrasting itself with those siblings.

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 when-to-use guidance at all: nothing tells the agent to prefer this over list_calls when only one ID is known, and no prerequisites or failure conditions are mentioned. Usage must be inferred entirely from the tool name.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It says only that it 'gets details' and does not state that the operation is read-only, what permissions are needed, what happens on invalid IDs, or what kind of details are returned.

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, front-loaded sentence with no redundant wording or unnecessary background. It is appropriately sized for the trivial surface it attempts to describe.

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 simple one-parameter getter, the description covers the basic purpose but leaves key gaps: there is no output schema, no annotations, and the description does not explain return shape, read-only behavior, or how it differs from list_phone_numbers. It is minimum viable but incomplete for safe tool selection.

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 100%, and the sole parameter phoneNumberId is already documented in the schema as 'ID of the phone number to get.' The description adds no additional meaning, format constraints, or usage hints beyond what the schema provides.

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 states a specific verb and resource: 'Gets details of a specific phone number.' The word 'specific' implies a single-resource lookup, which distinguishes it somewhat from list_phone_numbers, but it never names the sibling tool explicitly.

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?

Usage is only implied: the agent can infer this is for retrieving one phone number by ID. The description gives no explicit when-to-use guidance, no exclusion for list_phone_numbers, and no prerequisites or alternatives.

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

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

With no annotations at all, the description carries the full behavioral burden and does disclose the key quirk: results are capped at 100 item summaries, itemsTruncated signals omission, and itemsMetadata holds API pagination metadata. That is genuine behavior beyond the schema. It stops short of stating read-only semantics explicitly or any auth/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?

Three sentences, each doing distinct work: what is returned, how truncation is signaled, and where to go for per-item detail. The truncation caveat is placed before the sibling pointer, which is the right order for an agent deciding whether this result is sufficient.

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?

There is no output schema, so the description must convey the return shape, and it does so at a useful level (status, counts, 100 truncated item summaries, two metadata fields). It could be more complete about what the item summary objects contain or how itemsMetadata should be used to page further.

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 0% and the sole required parameter runId has no description in the schema or in the description text. The meaning is inferable from the tool's purpose (a simulation run identifier), and the uuid format in the schema removes most ambiguity, so the gap is small but real.

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 gives a specific verb and resource ("Gets a simulation run") and enumerates what comes back: status, item counts, and the first 100 item summaries. It also names the sibling get_simulation_run_item and states what that one returns instead, so an agent can separate the two tools without opening either 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?

It gives an explicit routing rule: use get_simulation_run_item for an item's transcript and call details. That covers the most likely sibling confusion, but it offers no guidance on when to reach for this tool versus list_simulation_runs or run_simulations, and no preconditions for runId.

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

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

With no annotations provided, the description carries the full behavioral burden. It usefully discloses the return payload (results, call snapshots, transcript, improvement suggestions), but it does not state that the operation is read-only, whether it has side effects, what permissions are required, or how invalid IDs are handled.

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 front-loaded sentence with no filler and efficiently lists the returned content. It could be slightly better structured by separating scope from return details, but it is appropriately concise.

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 simple two-parameter read tool with no output schema, the description conveys the single-item scope and the main returned contents. However, it omits parameter semantics and error or permission context, leaving important gaps for correct invocation.

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 0%, so the description must compensate for the undocumented runId and itemId parameters. It never explains what runId and itemId identify, their format, or how they relate to the returned item; it only indirectly alludes to an 'item.'

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 uses the specific verb 'Gets' with the resource 'one simulation run item' and clarifies scope with 'in full,' including the returned contents. It is clear what the tool does, but it does not explicitly contrast itself with the sibling get_simulation_run, so sibling differentiation is missing.

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 implies usage for retrieving a single simulation run item, but it gives no explicit when-to-use guidance, prerequisites, or alternatives such as list_simulation_runs or get_simulation_run. The implied use case is adequate but not directive.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It says nothing about what fields the returned details include, whether the lookup is read-only, or what happens for an invalid or nonexistent toolId — all important for a lookup tool with zero annotation coverage.

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 efficient sentence with no filler and the resource scoping front-loaded. Its brevity is appropriate for a one-parameter lookup, though it borders on under-specification.

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 simple one-parameter lookup with complete schema coverage, the description covers the minimum: what it fetches and by what key. Because there is no output schema, the description should have characterized the returned "details," which it does not, leaving a meaningful 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 description coverage is 100%, with toolId fully documented as a UUID with a pattern, so the description need not compensate. The description adds nothing beyond the schema, which is the expected baseline when the schema does the work.

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 names a specific verb and resource ("Gets details of a specific tool"), so the basic operation is identifiable. However, "details" is vague and never differentiates it from siblings such as list_tools, create_tool, update_tool, or get_api_schema, leaving the agent to infer what the returned details actually are.

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 versus alternatives like list_tools or get_api_schema, and no mention of prerequisites or lookup workflow. The only implied usage is that an agent must already have a toolId, which comes from the schema rather than the description.

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

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

With no annotations provided, the description carries the full burden and discloses nothing beyond the fact that it reads. It says nothing about pagination, result ordering, approximate result volume, or whether truncation occurs, all of which matter for a list endpoint with no output schema.

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?

A single front-loaded phrase with zero filler, which is the right shape for a no-parameter list tool. The brevity is efficient rather than padded, though it leaves the description barren.

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?

The tool is structurally simple (no params, flat, no output schema), so a short description is defensible, but a list operation with no annotations and no declared return shape still benefits from at least a note on pagination and return contents, which is missing.

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 takes zero parameters, so there is no parameter meaning to add; baseline is 4. The empty schema means there is nothing the description could clarify here.

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?

States a specific verb (Lists) and resource (Vapi assistants), which an agent can easily distinguish from get_assistant, create_assistant, and the unrelated list_* siblings by resource noun. It stops short of 5 because it does not explicitly contrast itself with get_assistant or note that it returns all assistants regardless of filters.

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 when-to-use guidance at all: no mention of when to prefer get_assistant for a single record, no prerequisites, and no indication of what the list covers (org-wide vs. a subset). The only usable signal is the name itself.

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

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

No annotations are provided, so the description must carry the full behavioral burden, but it discloses nothing about result size, ordering, pagination, or whether the listing includes all calls or only ones visible to the caller. That omission matters for a list operation over a potentially large collection.

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?

Four words with zero filler and the key concept front-loaded. It is trimmed, but the brevity is only acceptable because there is nothing else supplied; if it had more to convey, this would be under-specification rather than concision.

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 zero-parameter list tool with no output schema, the description should say what comes back, such as full call objects versus summaries, and how large result sets are handled. As written, it leaves the agent guessing about the return shape.

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 accepts zero parameters, so there is no parameter semantics for the description to explain, and the baseline of 4 applies. The empty schema leaves nothing ambiguous that the description needs to clarify.

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?

States a specific verb ("Lists") and resource ("Vapi calls"), so the basic operation is unambiguous. It adds nothing about scope, filtering, or pagination to separate it from the neighboring get_call and create_call tools beyond the plain verb, which keeps it at a minimum-viable 3.

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 when-to-use guidance and no mention of alternatives such as get_call for a single call. The agent must infer from the name alone that this tool is the bulk-retrieval path.

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

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

With no annotations provided, the description carries the full behavioral burden and discloses almost nothing beyond the fact of listing. It does not say whether results are paginated, whether the list is org-wide or credential-scoped, what fields each entry contains, or what an empty result means.

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?

A single short sentence with no filler and the resource front-loaded after the verb. It is efficient, though its brevity stems partly from under-specification rather than deliberate economy.

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 zero-parameter read tool this is close to adequate, but with no annotations and no output schema the description is the only source of behavioral information and leaves return shape, pagination, and scoping unstated. It is the minimum viable definition rather than a complete one.

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 takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-parameter tool applies. The description correctly implies a parameterless full listing.

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?

States a specific verb (Lists) and resource (Vapi phone numbers), and the word 'all' implicitly contrasts with the sibling get_phone_number. It does not explicitly name that sibling or clarify whether the listing is scoped to an organization, but an agent can still tell what the tool returns.

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 versus get_phone_number, and no mention of prerequisites such as authentication or org scope. Usage is only implied by the name and the word 'all'.

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

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

With no annotations, the description carries the full burden, and 'Lists' reasonably implies a non-destructive read. However, it says nothing about pagination or truncation behavior (the 50-default, 1000-max limit), whether an empty list is possible, or what fields a personality record contains — context an unannotated tool should supply.

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?

A single clause, front-loaded with the action and resource, with the colon-apposition earning its place by defining a domain term. Nothing extraneous.

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 one-optional-parameter list tool with a fully documented schema and no output schema, the description covers the essential question of what is being listed. It stops short of only minor extras such as default page size or return shape, which keeps it close to complete.

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 100% and the sole parameter 'limit' is fully documented in-schema with bounds and a default. The description adds no meaning beyond the schema, so baseline 3 is appropriate.

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?

States a specific verb ('Lists') plus the exact resource ('simulation personalities') and then defines what that resource is — 'the simulated callers (testers) used in Vapi simulations' — a term an agent may not otherwise know. The plural verb form cleanly separates it from the create_simulation_personality sibling.

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?

Usage is only implied by the verb: an agent can infer this is the enumeration tool for personalities versus create_simulation_personality. There is no explicit statement of when to reach for this over list_simulation_scenarios or list_simulations, and no note that limit caps the result set rather than returning everything.

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

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

With no annotations at all, the description carries the full behavioral burden yet only discloses sort order. It says nothing about pagination beyond the implicit limit, whether results are scoped to a workspace, permission requirements, or whether a truncated list is silently capped.

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?

A single short sentence with no wasted words and the ordering fact placed prominently. It is efficient, though the extreme brevity reads more as under-specification than deliberate concision.

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 filterable list tool with three parameters, one-third schema coverage, no annotations, and no output schema, the description leaves the agent without enough to call it confidently — especially for the undocumented status and targetId filters. It should at minimum explain what the filters select.

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 33% — limit is documented in the schema, but status (an enum with no stated meaning) and targetId (a UUID with no stated referent) are undocumented. The description adds no meaning to any of the three parameters, leaving a real compensation gap.

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 states a specific verb ('Lists') and resource ('simulation runs') plus an ordering guarantee ('newest first'), so an agent knows exactly what it returns. However, it never distinguishes this tool from close siblings like list_simulations or get_simulation_run, so there is no explicit sibling differentiation.

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 when-to-use or when-not-to-use guidance, no mention of alternatives (e.g. use get_simulation_run for a single run, list_simulations for the definitions), and no indication of when the status/targetId filters should be applied. Usage can only be inferred from the verb.

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

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

No annotations are supplied, so the description carries the full burden and it discloses almost nothing behavioral: not whether results are paginated or truncated at a default, not the ordering, and not the shape of a returned simulation. The only hint at read-only behavior comes from the name itself.

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?

Two short sentences, no filler, with the tool's action front-loaded and the entity definition immediately after. Every sentence earns its place.

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 simple single-optional-parameter list tool with no output schema, so the description need not explain return values. However, for a tool sitting among half a dozen simulation-related listers, it should say what a call returns in aggregate and how it relates to those siblings.

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 100% and the single optional limit parameter is fully documented in the schema, including its default of 50 and maximum of 1000. The description adds nothing about the parameter, so the baseline 3 applies.

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 gives a specific verb and resource ("Lists simulations") and the second sentence defines the entity as a scenario+personality pair, which implicitly separates it from list_simulation_runs and list_simulation_personalities. It stops short of naming those siblings outright, so an agent must infer the boundary.

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 statement of when to use this instead of list_simulation_runs, list_simulation_suites, or the personality/scenario listers, all of which appear in the sibling set. No prerequisites, no exclusions, no alternative routing.

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

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

No annotations are provided, so the description carries the full behavioral burden. It implies a read operation but never states that it is read-only, whether results are paginated, what the default ordering is, or what happens when the limit is exceeded; only the resource's meaning is explained.

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?

A single short sentence with the resource front-loaded and the gloss following immediately. It wastes no words, though the explanatory clause is more helpful for a human than for tool selection.

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 simple two-optional-parameter list tool with no output schema, the description covers the resource adequately. However, it omits filtering semantics for name and pagination behavior for limit, which an agent needs to invoke 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 50%: the limit parameter is documented in the schema (default 50, max 1000), but the name parameter has no description anywhere. The description does not clarify whether name filters, matches exactly, or some other semantics, so it fails to compensate for the uncovered parameter.

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 uses a clear verb 'Lists' and a specific resource 'simulation scenarios', then expands with a plain-language gloss ('the scripts testers follow and the checks that decide pass or fail'). It does not differentiate itself from close siblings like list_simulations or list_simulation_suites, so an agent must infer the distinction from names alone.

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 about when to use this tool rather than load_skill, list_simulations, list_simulation_suites, or get_simulation_run. The description offers no context, prerequisites, or exclusions, leaving selection entirely to the tool name.

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

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

No annotations are supplied, so the description bears the full disclosure burden, and it discloses almost nothing: it does not confirm this is a non-mutating read, does not mention the default page size of 50 or the 1000 cap, and says nothing about truncation, ordering, or what a returned suite contains. The definition is a one-line label rather than a behavioral account.

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?

One sentence, front-loaded with the verb and resource, with the clarifying gloss placed where it helps most. There is no filler, though the brevity is close to under-specification rather than disciplined economy.

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 simple list tool with one optional numeric parameter and no output schema, so the bar is low, and the description does define the resource. It still leaves out the things an agent needs for correct invocation at scale, namely that results are paginated by default and that the response shape is unspecified.

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?

There is a single optional parameter and schema description coverage is 100%, so the schema already explains limit, its default of 50, and its bounds. The description adds no extra meaning about pagination semantics, which is the baseline expectation at full coverage.

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?

"Lists simulation suites" states a specific verb and resource, and the gloss "named groups of simulations" defines the entity well enough to separate suites from the sibling list_simulations and list_simulation_scenarios. It stops short of naming those siblings explicitly, so the differentiation is inferential rather than stated.

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 when-to-use guidance, no mention of when a suite is the right thing to look at versus a simulation, scenario, or personality, and no prerequisites. The only signal is the implicit one carried by the verb "Lists".

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

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

With no annotations supplied, the description carries the full burden and provides almost nothing: no indication of pagination, result volume, ordering, or whether the listing is scoped to an org/workspace. For a listing endpoint whose main risk is unbounded result size, this is a meaningful 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?

A single front-loaded sentence with zero filler. It is arguably under-specified rather than verbose, but nothing in it is wasted.

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?

The tool is simple (no params, no nested objects), so the low description length is defensible, but with no output schema the agent has no idea what a returned tool object looks like or whether results are paginated. One more sentence on return shape would close the 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a 0-param tool is 4. The description is consistent with the empty schema by not describing any filter 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 gives a specific verb and resource ('Lists all Vapi tools'), and 'all' signals an unfiltered enumeration that contrasts implicitly with the sibling get_tool. It does not explicitly name any sibling, so an agent must infer the boundary itself.

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 when-to-use or when-not-to-use guidance, and no mention of the alternatives (get_tool for a single tool, search_skills-adjacent patterns for filtered lookup). The only hint is the word 'all', which is left for the agent to interpret.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description still adds value by clarifying the return contract (instructions for the task) and by ruling out side effects (no installing, no script execution). It doesn't mention size limits or errors for a missing path, which keeps it short of a 5.

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?

Three tight sentences with zero filler: purpose first, then the operating sequence, then the boundary condition. Nothing is buried, and every sentence carries distinct information.

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 only two well-documented parameters and no output schema, the description has to carry the return-value story, and it does: it says instructions come back plus a file list used for follow-up loads. It stops just short of describing what a skill file's contents look like or what happens when a path doesn't exist.

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 100%, so both parameters are already fully documented, including the SKILL.md default and the relative-path format. The description's mention of starting at SKILL.md and following the returned file list is workflow context rather than added parameter semantics, so the baseline 3 applies.

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?

A specific verb ("read") plus a specific resource ("a public Vapi skill or one of its supporting files") tells the agent exactly what the tool does. The closing clause ("does not install skills or execute scripts") separates it from anything that would mutate state or run code, and the two-parameter shape makes it easy to tell apart from siblings like search_skills.

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?

It gives real sequencing guidance: start with SKILL.md, then load relevant files from the returned file list as needed. What's missing is any pointer to search_skills for discovering the exact name (that hint lives only in the schema) and any explicit statement of when not to use it.

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

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

With no annotations, the description carries the full behavioral burden. It does add real value by stating that the call returns the run with its ID and a shareable dashboard URL, and by implying the run is started asynchronously since progress must be polled via get_simulation_run. It says nothing about idempotency behavior, iteration limits, failure modes, or any permission requirements involved in starting a run.

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?

Three short sentences, front-loaded with the action, then the return value, then the follow-up tool. Every sentence carries distinct information with no restatement or 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 a seven-parameter launch tool with no annotations and no output schema, the description covers the essentials: what it starts, what it returns, and how to monitor it. The remaining gap is the undocumented idempotencyKey and any statement about run duration or expected errors, which keeps it short of complete.

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 57%, so the schema already explains assistantId, squadId, simulationIds, suiteIds, iterations and transport. The description only restates the mutual-exclusion shape ('simulations and/or suites against an assistant or squad'); it adds no guidance on idempotencyKey, the only parameter lacking any schema description, nor on how iterations interacts with the run.

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 verb and resource ('Starts a simulation run') and states the target ('of simulations and/or suites against an assistant or squad'), which mirrors the schema's mutual-exclusion groups. It is immediately distinguishable from get_simulation_run and list_simulations, which read state rather than launch it.

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?

It gives clear context for when to reach for this tool (launching a batch run of existing simulations or suites) and explicitly routes the agent to get_simulation_run for progress polling. It does not, however, position it against siblings like create_simulation or list_simulations, nor state any prerequisites such as needing an existing assistant or squad ID.

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

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

Annotations already declare readOnlyHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description still adds real context: the search target is a public GitHub-hosted repository (consistent with openWorldHint), and results are pointers that must be fetched with load_skill rather than full skill bodies. It does not mention ranking, 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?

Three short sentences, front-loaded with what it searches and where, followed by the browse case and the follow-up tool. No filler, no restatement of the tool name or annotations.

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 two-parameter read-only search with no output schema, the description covers purpose, the empty-query behavior and the read follow-up, which is enough to call it correctly. The only loose end is the undocumented 'limit' parameter, whose default and cap of 30 live in the schema but carry no explanation of ordering or result-count tradeoffs.

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 50%: the 'query' parameter already documents itself as keywords or empty-to-browse, so the description's wording largely mirrors the schema. The description does add the match fields (name, description, content) which the schema omits, but the 'limit' parameter is left entirely unexplained in both places, keeping this at the baseline.

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 states a specific verb and resource ('Find Vapi agent skills') and names the exact repository, scope and match fields (name, description, content). It also distinguishes itself from the sibling that consumes its output ('Use load_skill to read a result'), so an agent can separate search from read without opening either 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?

It gives a concrete usage condition ('Omit query to browse') and routes the agent to the correct follow-up tool (load_skill) for reading a hit. It stops short of an explicit 'do not use this for X' exclusion or guidance on when to prefer ask_vapi_docs, so it is clear but not fully exhaustive.

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

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

With no annotations supplied, the description carries the full behavioral burden and does not meet it. It never states whether this is a partial merge or a full replace (critical for a 9-parameter update tool where omitted fields may be wiped), whether the change is reversible, what permissions or auth are needed, or what the response contains.

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 single sentence is front-loaded and free of filler, but its brevity reflects under-specification rather than discipline. There is no wasted wording to cut, yet almost every sentence that would earn its place is missing.

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 mutation tool with 9 parameters, nested objects, an enum, no output schema, and no annotations, a five-word description leaves major gaps. An agent cannot tell whether omitted fields are preserved or cleared, nor what a valid voice/llm object requires, without reading the schema closely.

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 100%, so every parameter including the nested llm, voice, and transcriber objects is already documented in the input schema. The description adds no extra meaning - no format hints for llm/voice objects, no note on the firstMessageMode enum behavior - so the baseline 3 applies.

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?

"Updates an existing Vapi assistant" names a specific verb and resource, so the basic action is unambiguous. However, it offers no differentiation from siblings such as create_assistant or get_assistant, and it says nothing about which aspects of the assistant are updatable - all of that has to be recovered from 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?

There is no when-to-use guidance at all: nothing tells the agent to prefer create_assistant for new assistants or get_assistant for read-only inspection. No prerequisites, no mention of whether the assistant must already exist beyond 'existing', and no guidance on partial vs. full configuration replacement.

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

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

No annotations are provided, so the description carries the full burden and supplies almost nothing. It does not say whether this is a full replace or a partial merge, what happens to omitted fields, whether mutations are reversible, or whether the tool type can be changed after creation — all critical for a mutation tool with no annotation coverage.

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 single sentence is efficient and front-loaded with the verb, so nothing is wasted. But at this length for an 8-parameter polymorphic mutation tool the brevity reads as under-specification rather than concision, leaving the key update semantics unstated.

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 a nested schema with 8 parameters and four mutually plausible tool-type configurations, plus no annotations and no output schema, the description is far too thin to guide a correct call. The rich schema descriptions partially compensate, but the agent still cannot determine partial-vs-full update behavior or success/failure characteristics.

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 88% and each of the 8 parameters (sms, function, apiRequest, transferCall, toolId, name, description, additionalFields) is documented in the schema itself, so the schema does most of the work. The description adds no meaning beyond that, including no clarification of whether multiple configuration blocks can be passed together, which the schema leaves ambiguous.

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 states a specific verb and resource ("Updates an existing Vapi tool"), so the agent knows this is a mutation on a tool entity. However, it offers no differentiation from sibling tools such as create_tool, get_tool, or list_tools sharing the same resource, and it does not indicate which tool types are modifiable.

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 instead of create_tool or get_tool, no prerequisites (does the tool already have to exist?), and no note that only one of the polymorphic configurations (sms, function, apiRequest, transferCall) should be supplied. Usage is only implied by the word "Updates".

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