Word Is Bond

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

With no annotations, the description carries the full burden. It discloses meaningful behavioral context: the judge scores every ingested call against scenarioGoal, assertions are checked, the ingest secret must be fetched via a specific endpoint, and a plan requirement exists. It does not cover all possible side effects or response shape, but the provided details go well beyond a minimal mention of creation.

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 compact and front-loaded. It leads with the core purpose, then adds essential clarifications about the two most important parameters, a critical follow-up action (reading the secret), and a plan requirement. Every sentence earns its place with no filler or redundancy.

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 creation tool with 7 parameters and no output schema, the description covers the purpose, key parameter semantics, plan constraints, and a necessary post-create action. It does not describe the response body or error handling, but it gives enough operational guidance to use the tool effectively. A small gap remains around what the tool returns upon success.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds genuine value for scenarioGoal by explaining it as "what GOOD looks like" and comparing it to test scenario goals, and for assertions as "plain-English checks." Other parameters are left to the schema, but this added semantics lifts the score above 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 opens with the specific verb+resource pattern "Create a production monitor," clearly distinguishing this from sibling tools like create_suite. It further clarifies the core semantic of scenarioGoal and the judge/scoring model, leaving no ambiguity about what the tool creates and for what purpose.

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?

Clear context is provided: this is for production monitoring, and it requires a pro or enterprise plan. However, it does not explicitly state when to prefer this over alternatives such as run_test or create_suite, nor does it mention exclusions or fallback tools.

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 must carry the transparency burden. It discloses that schedules are 'plan-gated' and that the suite 'flags drift', which adds behavioral context. However, it does not mention side effects like persistence, immediate vs. scheduled execution, or verification requirements for PSTN targets (those live in the schema, not the main description).

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 two sentences, front-loaded with the resource definition and optional schedule. It is concise, with no wasted words, and earns a high score for structure.

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 description covers the tool's purpose and the optional schedule, but with no output schema it omits what is returned (e.g., suite ID). It also doesn't explain the verification requirement for PSTN targets, which is only in the schema. For a create tool with nested objects, this is adequate but not 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 80%, so the baseline is 3. The main description repeats schedule values and mentions scenarios/personas, but it does not add meaning beyond the schema. Since the schema already documents each parameter well, the description does not need to compensate.

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 resource ('reusable test suite') and action ('create'), and elaborates with 'named set of scenarios/personas pinned to a target voice agent you run'. This is clearly distinct from sibling tools like run_test or create_monitor, as it emphasizes reusability and optional scheduling.

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 persistent, scheduled test suites ('reusable', 'optionally give it a schedule so it runs automatically'), but it does not explicitly state when to choose this over run_test or create_monitor, nor mention any exclusions. The guidance is implicit rather than explicit.

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. It signals a read-only operation through 'Show' and describes the output semantics (added/removed/changed nodes and edges). While it doesn't cover authentication or rate limits, the non-destructive nature is clear and sufficient for this type of tool.

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 two sentences, front-loaded with the core function and followed by a memorable analogy. Every word serves a purpose; no padding or redundancy.

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 description explains what the tool returns (structural diff of nodes and edges), when to use it (before shipping), and the parameters are fully documented in the schema. No output schema is present, but the description adequately communicates the return concept for this simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and each parameter is already well-described ('Base version number', 'Target version number', 'The flow id'). The tool description adds no extra parameter-level detail beyond the metaphor, aligning with the baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Show the structural diff between two versions of a version-controlled flow: which nodes and edges were added, removed, or changed.' This is a specific verb+resource combination that distinguishes it from siblings like import_flow or test_flow.

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 a use case ('see exactly what a change did before you ship it') but does not explicitly compare to alternatives such as test_flow or import_flow. No when-not-to-use guidance is given, making the usage context implied rather than explicit.

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. It goes above and beyond by specifying the possible health values (unknown | healthy | degraded | critical) and the nuanced drift behavior: judge changes are reported as judgeVersionChanged and never as an agent regression. This critical caveat—that a score delta across a judge change says nothing about the agent—is essential for correct interpretation and is not obvious from any structured data.

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 extremely concise: two sentences. The first sentence front-loads the core purpose and scope. The second sentence packs important behavioral details about health and drift, and every clause earns its place. There is no fluff, repetition, or irrelevant 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?

For a tool with minimal schema and no output schema, the description provides enough context to understand what the tool returns (health status and drift) and the key interpretation caveat. It does not explicitly describe the exact return structure (e.g., field names), but the information given covers the essential semantics. Given that the tool is simple, the description is nearly complete but could be improved with a brief mention of 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 schema has 100% coverage for the single parameter monitorId, with the description 'The monitor to read.' The tool description itself does not add any further parameter-level semantics beyond what the schema already provides. Since the schema fully documents the parameter, the baseline score 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?

The description begins with 'Read a monitor's live rolling health and drift,' which clearly states the verb (read), resource (monitor health), and scope (live rolling). This distinguishes it from sibling tools like get_trends or list_monitors, which serve different purposes. The explicit mention of 'health and drift' makes the tool's purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: this tool is for reading monitor health and drift. However, there is no explicit guidance on when to use it versus alternatives such as get_trends or list_monitors, nor when not to use it. The drift isolation explanation is helpful for interpreting results but does not address tool selection, so the guidance is only implicit.

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 burden. It states 'Read' which implies read-only, and lists what the tool returns. However, it does not disclose limitations, potential edge cases (e.g., empty results), or any operational implications. It provides basic transparency but not deeper behavioral context.

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 pack a clear purpose, output summary, and a use case. There is zero redundancy and the key information is front-loaded. 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?

Despite having no output schema, the description explicitly lists return contents (pass-rate, average score, regressions, totals). With only one optional parameter already documented in the schema, the description fully covers the tool's simple scope and context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%: the sole parameter 'days' is fully described with min, max, and default. The description's phrase 'over a window' aligns with the parameter but adds no extra meaning beyond the schema. 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 uses a specific verb 'Read' plus a clear resource: 'account-wide testing trends over a window'. It enumerates the output (pass-rate, average score, run-to-run regressions per suite, overall totals) and gives a concrete use case, distinguishing it from sibling tools like get_monitor_health.

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 says 'Use this to spot behaviour drift in the voice agents you test', which provides clear when-to-use context. It does not mention alternatives or exclusions, but the use case is sufficiently specific to guide selection.

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 burden of behavioral disclosure. It explains that the tool reports abstracted fields, supports a save:true parameter to persist the flow, and that the IR can be exported back out—useful migration context. It doesn't cover all edge cases (e.g., idempotency, failure modes), but covers the key behaviors well.

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 packed with relevant info: purpose, ability to report abstracted fields, save behavior, and migration use-case. No filler; front-loaded with the core purpose.

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 complex tool with nested objects and no output schema, the description covers purpose, usage context, save behavior, and what the tool reports. It's slightly light on return-value format, but the statement 'Reports the fields the IR abstracts away' gives a clear idea of the output. Good overall completeness.

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 parameters are well-documented already. The description adds extra semantics beyond the schema: it clarifies that save:true persists the imported IR, that name defaults to config name, and that the config is platform-native. This elevates it above 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 clearly states the tool's function: importing a phone-system flow or voice-agent config into the canonical, diffable Flow IR. It uses a specific verb ('Import') and resource ('Flow IR'), and distinguishes itself from sibling tools like diff_flow and test_flow by positioning this as the first step in version control.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use it: as the first step of putting a phone system under version control and as a migration surface between platforms. It doesn't explicitly mention alternatives, but the contrast with sibling tools (diff, test) makes the usage context unambiguous.

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 fully discloses key behaviors: returns 202 immediately, background scoring, transcript never stored, only scorecard and safe metadata kept, and idempotent handling via externalId. This is rich, operationally critical information.

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 concise sentences, each packed with distinct information: purpose, async behavior, data handling, and idempotency tip. No fluff, front-loaded with the core action.

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 6-param tool with no output schema, the description covers the essential operational aspects: async return, background processing, data retention, and idempotency. It doesn't describe response body or error cases, but covers the most critical context 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 coverage is 100%, so baseline is 3. The description adds meaningful context beyond schema, especially for externalId (idempotency guarantee) and transcript (scored in flight, never stored), which enhances the agent's understanding of how these params affect behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action: 'Send one completed PRODUCTION call to a monitor to be scored.' This distinguishes it from sibling tools like run_test or run_demo by emphasizing production calls and the ingestion aspect.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context: it's for completed production calls and explains the async behavior and idempotency via externalId. It doesn't explicitly name alternatives, but the production qualifier and 'one completed call' guide appropriate use.

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. It explains what monitors are (watches one live production line, streams calls, scores with a versioned judge, tracks rolling baseline, alerts on drift), and states the plan requirement. This provides useful context beyond a simple 'list' statement, though it does not detail return format or error behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is structured with the core statement first, followed by explanatory context. The second sentence is somewhat long but informative, and the third states a requirement. Every part earns its place, but the middle sentence could be tightened without losing significant value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that the tool has no parameters, no output schema, and a simple listing function, the description is complete enough. It defines the health states, explains the monitor concept, and notes the plan requirement. No additional details are necessary for correct selection and 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?

The input schema has zero parameters, so the baseline is 4. The description adds no parameter information, but none is needed. It is sufficient for a no-argument list operation.

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 'List' with a clear resource ('your production monitors') and outcome ('their current health'), including the possible health values. This clearly distinguishes it from sibling tools like get_monitor_health, which presumably targets a single monitor.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when to use this tool (to list all production monitors with health status) and includes a prerequisite (requires pro or enterprise plan), but it does not explicitly mention alternatives or when not to use it. The distinction from get_monitor_health is implied but not directly stated.

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 full behavioral burden. It communicates a read-only operation via the verb 'List' and discloses return contents. It doesn't cover error cases or pagination, but for a simple list tool this is acceptable.

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 two sentences, front-loaded with the core action, and every sentence provides value: definition of suite, return fields, and follow-up usage. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter tool with no output schema, the description is complete. It explains what a suite is, what the tool returns, and how to use the results with other tools. There is no missing critical information.

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 are zero parameters, so the description doesn't need to explain any. The empty input schema is fully covered by the absence of params, and the description adds no ambiguity. Baseline for 0 params is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List your reusable test suites' with a specific verb and resource, and explains what a suite is. It distinguishes from siblings like list_monitors and run_test by specifying the resource type and return fields (ids, names, targets, schedules).

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 provides a clear use case by stating 'use a suite id with run_test or get_trends,' which tells the agent when to use this tool and how the result connects to other tools. It doesn't explicitly mention when not to use it, but the context is sufficient for a list operation.

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 transparency burden. It discloses the scope (numbers your account controls) and the constraint on PSTN target usage, but does not describe return structure, pagination, or other behavioral traits. It clearly implies a read operation but lacks explicit safety guarantees or side-effect disclosure.

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 extremely concise with two sentences, front-loading the main purpose and then adding valuable context about usage constraints. Every sentence earns its place, with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with no output schema, so the description must explain the return value. It states it lists phone numbers and implies an ID via the DELETE reference, but does not explicitly describe response fields or format. This is a minor gap for a simple listing tool, hence a neutral score.

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 parameters, so the schema is fully self-explanatory. The description adds no parameter details needed, and the baseline of 4 is appropriate since no parameter clarification is necessary.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'List' and the resource 'phone numbers your account has proven it controls', making the purpose unambiguous. It also distinguishes from sibling verification tools by focusing on the list of confirmed numbers rather than the verification process.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context that these numbers (and Word Is Bond DIDs) are the only valid PSTN targets, implying when this tool should be used. It mentions revoking via DELETE but does not explicitly exclude alternatives or state when not to use this tool, though the usage context is strong.

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?

Despite having no annotations, the description goes into significant behavioral detail: it states wordis-bond keeps only a pointer and never audio, explains the presigned PUT URL mechanism to avoid holding cloud credentials, and discloses plan limitations (starter gets 402). This exceeds what an annotation would typically provide.

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 three sentences, each dense with information: purpose, behavior, callback mechanism, pricing. No wasted words, and the key purpose 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 description covers the tool's purpose, workflow, constraints (public https, presigned PUT), and plan restrictions. It doesn't describe the response format, but for a simple registration tool with no output schema, this is a minor gap. The overall context is complete enough for an agent to use it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already covers all parameters with descriptions (100% coverage), so the baseline is 3. The description adds meaningful context beyond the schema: it explains that callbackUrl must be a public endpoint that mints presigned URLs per recording and clarifies that 'inbound' means the agent. This adds value without being redundant.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Register where BYOS call recordings go' and explains its usage in the context of run_test with record:true. This is a specific verb+resource pair that distinguishes it from sibling tools like run_test or ingest_call.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use the tool (when you want call recordings teed to your own storage) and ties it to run_test's record:true flag. It does not explicitly mention alternatives or exclusions, but the usage context is unambiguous.

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 full burden and does well: it discloses that the result is 'real, fully-scored', lists the return values (score, verdict, metrics, transcript, public URL), states 'Zero carrier cost', and gives a time estimate ('about a minute'). It could mention potential side effects or limitations, but for a demo tool the described behavior is quite transparent.

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 three sentences, each earning its place: the first states the core action and scope, the second lists the outputs, the third addresses cost and input flexibility. It is front-loaded with the most important information and contains zero waste.

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?

Despite having no output schema, the description enumerates the expected return values (score, verdict, metrics, transcript, URL), which is critical for the agent to know what to expect. It also covers timing, cost, and input override semantics. The schema handles parameter details, and together they give a complete picture for invoking the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already covers all 5 parameters with descriptions (100% coverage), so the baseline is 3. The description adds meaningful context by stating 'Optional inputs override the scenario', clarifying that these parameters are optional modifications to a default scenario rather than required inputs. This goes beyond the schema and helps the agent understand parameter 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?

The description clearly states the tool's function: 'Run the hosted demo voice agent (a dental front desk) end-to-end' and get a scored result. It distinguishes this from sibling tools (e.g., run_test, test_flow) by emphasizing 'no target of your own needed', clarifying it is for a pre-hosted demo rather than user-provided flows.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context: use this when you don't have your own target, as it explicitly says 'no target of your own needed'. It also notes 'Optional inputs override the scenario', implying the default scenario runs without any overrides. It does not name alternative tools directly, but the context is strong enough to guide selection.

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. It reveals that offline runs return synchronously, live direct targets yield a tokenized media WebSocket URL, pstn calls require verified numbers and return 403 NUMBER_NOT_VERIFIED if unverified, and live runs must be polled for terminal state. This is substantial and exceeds typical 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 dense single paragraph but is front-loaded with the two-mode structure and every clause contributes essential info. It avoids fluff and waste. A little more visual structure (bullets or line breaks) would earn a 5, but it remains readable and appropriately sized for the tool's complexity.

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 complex tool with 15 params and no output schema or annotations, the description covers modes, required inputs, transport behavior, error handling, and the polling mechanism. It tells the agent exactly what to pass and how to obtain results. The schema handles parameter details, while the description supplies the contextual glue needed 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 coverage is 87%, so the schema already documents most parameters. The description adds value by grouping parameters by mode: transcript/turns/scenarioGoal for offline and targetAgent/goal for live. It also clarifies the behavioral implications of targetAgent transport options, including the 403 error and plan restrictions, going beyond the schema's field descriptions.

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 clear statement: 'Run a test against a voice agent you control.' It then disambiguates two concrete modes—offline transcript scoring and live synthetic calls—making the tool's function and scope immediately apparent. This distinguishes it from sibling tools like run_demo or test_flow.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance for both modes: pass 'transcript' (or 'turns') plus 'scenarioGoal' for offline scoring; pass 'targetAgent' and 'goal' for live calls. It also explains transport-specific constraints (direct vs pstn, plan requirements, verified numbers) and refers to polling via get_run. It doesn't explicitly name alternative tools, but the mode guidance is strong.

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 bears the full burden and does well by disclosing the core behavior: compiling, running a synthetic-caller test, comparing to baseline, catching regressions, and blocking changes. It lacks detail on the exact result format or runtime side effects, but the main traits are transparent.

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 two sentences, front-loaded with the primary action "Run the regression gate on a flow now" and then packed with relevant procedural detail. Every sentence earns its place; there is no fluff or repetition.

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 single-parameter tool with no output schema, the description provides substantial process context (compile, run, compare, block) and explains the purpose of the tool. The main gap is that it does not describe what the caller can expect in the response (e.g., pass/fail report), but given the low complexity, this is a minor omission.

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 input schema has 100% coverage for flowId with a clear description, so the baseline is 3. The tool description adds contextual meaning by explaining what the flow is used for (compiled into a synthetic-caller test) but does not meaningfully enhance the parameter's meaning 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 clearly states the tool's function: "Run the regression gate on a flow now" and details the steps (compile, run, compare). It distinguishes itself from siblings like run_test and diff_flow by explicitly focusing on regression detection and blocking changes, making its unique purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description establishes clear usage context as a continuous-integration regression gate ("continuous integration for your phone-system logic") but does not explicitly name alternatives or state when not to use. It implies usage when checking for regressions, which is sufficient though not 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?

No annotations are provided, so the description carries full responsibility. It discloses key behaviors: code is single-use, expires after ten minutes, and locks after five incorrect attempts, plus the successful outcome (number becomes a permitted PSTN test destination). This provides substantive behavioral context beyond just the operation.

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 concise sentences with no unnecessary words. The description front-loads the action and mechanism, then states the outcome and important constraints. Efficient and well-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 description adequately covers the tool's purpose, workflow position, and safety constraints. Since there is no output schema, the description doesn't describe return values, but the key effect (number becomes permitted) is stated. A minor gap remains regarding response format, but overall complete for the tool's simplicity.

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 input schema already describes all parameters at 100% coverage, so the baseline is 3. However, the description adds critical context for the 'code' parameter: it is spoken on the call and has lifecycle constraints (single-use, expiry, lockout). This enrichment justifies a 4.

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 ('Finish verifying') with a clear resource ('phone number') and mechanism ('6-digit code'), and distinguishes itself from sibling tool verify_number_start by indicating this is the completion step.

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 'Finish verifying' phrasing clearly implies this is the second step after verify_number_start, providing context for when to use it. However, it doesn't explicitly name the alternative or state when not to use it, so it misses the 'explicit when/when-not' threshold for a 5.

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 fully discloses the behavior: it places one short call, speaks a 6-digit code twice, hangs up, and requires confirmation within ten minutes. It also explains the no-op behavior for already-verified numbers and the rate limits, leaving no hidden surprises.

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 four sentences, every one of which adds value: purpose, behavior, next step, and limitations. It is front-loaded with the most important information and avoids redundancy.

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 single-parameter tool with no annotations or output schema, the description is remarkably complete. It covers prerequisites, the call process, timeout, next steps, and rate limits, making it sufficient for an agent to invoke and handle the flow correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single parameter 'number', with a clear E.164 format example. The description does not add extra parameter semantics beyond this, so the baseline of 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 uses a specific verb ('Prove your account controls a phone number') and clearly identifies the resource (a phone number) and the context (before any PSTN test call). It distinguishes itself from siblings by naming verify_number_confirm and stating 'This is the only action that dials an unverified number.'

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 this tool ('before any PSTN test call'), what to do next (confirm with verify_number_confirm), and even notes that calling an already-verified number places no call. It also clarifies the tight call caps, providing clear guidance on usage limits.

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