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

Annotations cover only openWorldHint, so the description carries most of the burden. It does disclose a genuine side effect beyond the annotations — that tokens are stored — but says nothing about whether existing tokens are overwritten, token lifetime/expiry, failure modes, or required scopes.

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 that names the input, the output, and the persistence side effect with zero filler. Nothing could be trimmed without losing 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 two-parameter OAuth exchange with no output schema, the description covers the core action but omits the prerequisite flow (auth_url), what happens on redirect_uri mismatch, and how the newly stored tokens relate to any pre-existing session. Adequate but with real gaps.

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

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

Schema description coverage is 100% for both parameters, so the schema already explains 'code' and the redirect_uri matching constraint. The description adds no format, source, or validation detail beyond what the schema provides, 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 (exchanges) and concrete resources (web-flow authorization code → CTM OAuth tokens), so the operation is unambiguous. It implicitly separates itself from ctm_voiceai_auth_login and ctm_voiceai_auth_url by naming the web flow, though it never explicitly contrasts 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?

No when-to-use guidance, prerequisites, or alternatives are given. An agent must infer that this runs only after a browser redirect from ctm_voiceai_auth_url, and nothing explains why one would pick this over ctm_voiceai_auth_login.

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?

Only openWorldHint is annotated, which carries little safety information, so the description bears most of the burden and does disclose that tokens are stored and no API key is needed. It still omits token lifetime, refresh behavior, and failure modes, so it's helpful but not complete.

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 tight sentences that front-load the operation and then the two-phase flow. No wasted words, though the parenthetical 'or pass wait_seconds' slightly glosses over the polling semantics already in 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?

For a one-parameter, zero-required auth tool with no output schema, the description covers the device flow and token storage adequately. It could mention verification_uri expiry or the polling interval, but nothing an agent strictly needs 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?

Schema description coverage is 100% and the single parameter is fully documented in the schema, so the baseline of 3 applies. The prose echoes the wait_seconds polling behavior without adding syntax or edge-case 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 states a specific verb (logs in) and resource (CTM via OAuth2 device flow), and it explains the full flow. It doesn't explicitly differentiate from nearby siblings like auth_exchange or auth_url, so it's clear but not fully distinguished from alternatives in the auth family.

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 implies the two-phase usage (call, then call again or pass wait_seconds), which is genuine guidance, but it never says when to prefer this over auth_url or auth_exchange, nor when not to use it. Usage is implied rather than explicitly scoped.

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 destructiveHint=true, so the safety profile is covered. The description adds useful specifics (it deletes both tokens and any pending device-flow session), which is real context beyond the annotation, but it omits irreversibility implications and post-logout auth state.

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. Every clause (tokens, pending device-flow session) adds 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?

For a zero-param destructive auth tool with an annotation present, the description is minimally sufficient. It does not address whether logout affects concurrent sessions, whether re-auth is required, or what happens to in-flight device flows, which an agent might need to reason about.

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?

Zero parameters, so the baseline is 4. There is nothing to document, and the description consistently reflects a parameterless 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?

States a specific verb (deletes) and resource (stored CTM OAuth tokens / pending device-flow session). The scope is precise enough to distinguish it from siblings like ctm_voiceai_auth_login and ctm_voiceai_auth_status.

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 invocation context (cleaning up auth state) is implied by the destructive verb and token target, but there is no explicit when-to-use guidance or mention of what to do afterward. Adequate but leaves inference to the agent.

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 only readOnlyHint=true in annotations and no output schema, the description carries most of the return-value burden and does so by naming the four things reported (stored?, expiry, scope, account id). It does not disclose behavior when no tokens exist (error vs empty result) or any sensitivity around exposing scope/account id.

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; every clause (stored state, expiry, scope, account id) maps to something an agent would want to learn from the call.

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-only diagnostic with no output schema, the description supplies the essential return-field information an agent needs. The only real gap is the unspecified behavior on the unauthenticated/empty case.

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?

This tool takes zero parameters, so the baseline of 4 applies. No description of arguments is needed and none is given.

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+resource ("Reports whether CTM OAuth tokens are stored") and enumerates the inspected fields (expiry, scope, account id). It is clearly distinguishable from the auth_login/auth_logout/auth_exchange siblings by being the read-only status check, though it never names them 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 when-to-use guidance at all: nothing says to call this before the auth_* family, or what it means if tokens are absent. The diagnostic purpose is only implied by the name and field list, not stated as a usage rule.

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?

readOnlyHint=true already signals a safe, non-mutating call, so the description adds flow-level behavior beyond annotations: the URL is meant to be opened in a browser and the result is a redirect carrying a ?code=. It doesn't mention URL/token expiry or scope defaults, but the essential handoff behavior is disclosed.

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 does, then how to use the result. Every sentence earns its place with no 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 3-param, no-output-schema tool in an OAuth sequence, the description covers purpose, usage, and the next step. It could state that the return value is the URL string itself, but the flow is otherwise complete enough to invoke 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 67% (state has no description). The description clarifies redirect_uri's role ('CTM redirects to your redirect_uri with a ?code=') but says nothing about scope or state, so it only partially compensates for the coverage 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?

Specific verb+resource: 'Builds the OAuth2 authorization URL for the web flow.' It clearly distinguishes itself from siblings ctm_voiceai_auth_exchange and ctm_voiceai_auth_login by naming the web-flow URL as its output.

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?

Explicit sequencing: open the URL in a browser, CTM redirects to redirect_uri with a ?code=, then call ctm_voiceai_auth_exchange with that code. This names the exact follow-up tool and the condition for using 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?

Annotations declare readOnlyHint=true, covering safety. The description adds a meaningful behavioral guarantee—'Never reveals secrets'—and clarifies what is displayed, which is useful context beyond the annotation. It does not cover auth requirements or response format, but for a no-arg read tool this is adequate.

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 concise sentences, front-loaded with the tool's output and a security assurance. 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?

Given the tool's simplicity (no parameters, no output schema), the description sufficiently enumerates what is returned and adds a safety guarantee. It omits whether authentication is required first, a minor 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?

Zero parameters, so the schema provides no parameter semantics; baseline for 0 params is 4. The description appropriately does not discuss parameters.

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 'Shows' and resource 'configured CTM VoiceAI settings', and enumerates the four settings returned. It distinguishes itself from siblings like auth_status by covering broader configuration, though it does not explicitly name the alternative.

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?

No explicit when-to-use, prerequisites, or alternatives. The implied context (view configuration) is present, but an agent must infer that this is the right tool versus ctm_voiceai_auth_status for login state.

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 cover the safety profile (readOnlyHint, openWorldHint), so the bar is lower. The description adds real value beyond that: it discloses the response shape (a `plan` with total_pages and batches), the default target_calls of 500, and that transcripts are truncated, giving an agent the behavioral context to plan the fan-out.

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?

Front-loaded with the flow position and the single GET, then layers the response structure and dispatch instruction. Dense but every sentence earns its place; no filler or repetition 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 nine-parameter, multi-step fan-out tool with no output schema, the description is fairly complete: it explains the returned `plan`, the batch model, and the per-call fields, effectively compensating for the missing output schema. Auth/permission preconditions are the only notable 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 coverage is 100%, so the schema already documents all nine parameters and the baseline is 3. The description reinforces a few params (default target_calls 500, transcript truncation via max_transcript_chars) but adds little syntax or meaning the schema doesn't already carry.

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: 'one GET against the CTM calls endpoint returning a page of answered calls with transcriptions.' This is precise and an agent can tell it apart from the auth/run-status siblings, though it never explicitly names an alternative tool the way the top-tier examples do.

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?

Frames the tool as 'Step 3 of the review flow' and prescribes the workflow: 'Dispatch one subagent per batch; each subagent calls this tool with that batch's page and per_page.' Clear procedural context, but no when-not-to-use guidance or named 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?

readOnlyHint=true already establishes the safe-read profile, so the bar is lower. The description adds meaningful context beyond the annotation: it discloses the return content ('full current instructions'), states the optional single-agent filter, and explains the intended comparison workflow with get_calls. It does not, however, describe pagination, empty-result behavior, or auth requirements.

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 tightly written sentences, front-loaded with the step and purpose, then the filter, then the workflow linkage. No filler 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 readOnlyHint, full schema coverage, and only two simple parameters, the description covers purpose, filtering, and return content adequately. Minor gaps remain around behavior with no matching agents and any auth/account-scoping prerequisites, but nothing essential to correct invocation 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?

Schema description coverage is 100%, so the baseline is 3. The description largely restates what the schema already states about voice_bot ('Optional agent id or name substring') without adding format or matching-rule detail, so it earns no premium over 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?

States a specific verb and resource ('returns the account's VoiceAI agents and their full current instructions') and positions itself within a workflow ('Step 2 of the review flow'). It distinguishes itself from siblings by explicitly naming ctm_voiceai_get_calls as the complementary tool, so an agent can tell them apart 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?

Gives clear context for when to use it ('Step 2 of the review flow') and names the related tool (ctm_voiceai_get_calls) whose output it is compared against. It lacks explicit when-not-to-use guidance or filtering conditions (e.g., when to omit the voice_bot filter), so it falls short of a full 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?

The readOnlyHint annotation already declares this a safe non-mutating read, so the description adds the useful ordering detail ("newest first"). However, it says nothing about default results count, pagination, or return shape, and gives no explanation for why a read-only listing tool accepts an out_dir parameter.

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 efficient sentence with the key qualifier ("newest first") front-loaded and no filler. It is appropriately sized, though it errs toward under-specification rather than over-verbosity.

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 listing tool with no output schema, the description should at least bound the result set and explain out_dir. With two undocumented parameters, no pagination detail, and an unexplained write-like parameter on a readOnly tool, an agent lacks what it needs to invoke this confidently.

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 description mentions neither parameter. limit is loosely implied by "recent" but the cap (max 100) and default are not addressed, and out_dir — an unexplained output-directory argument on a read-only list tool — is entirely undocumented in both schema and description.

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 ("Lists") and resource ("VoiceAI analysis runs") plus ordering ("newest first"), so an agent knows exactly what it returns. It does not explicitly differentiate itself from siblings like ctm_voiceai_run_status or ctm_voiceai_get_calls, which is the only reason it falls short of a 5.

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 ctm_voiceai_run_status (single run) or ctm_voiceai_get_calls. "Recent" is undefined — no bound on how many runs are returned or how far back "recent" reaches, leaving the agent to infer selection criteria.

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 readOnlyHint already covering the safety profile, the description adds real value: it discloses the status enum, that output file paths are returned, and that the log tail is only included while running or failed. It stops short of mentioning auth requirements or pagination, so it earns a solid but not top score.

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 tight sentences with the core purpose front-loaded and no filler. The only soft spot is the dangling reference to 'recommended_prompt_updates', a field that appears in neither the schema nor a sibling, which a reader has to take on faith.

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 read-only status tool with no output schema, the description carries the return-value burden and covers status, output paths, and log tail. However, it leaves out_dir undocumented and references an unexplained field, so an agent still has gaps to fill.

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 only 50%: run_id is well documented in the schema (returned by ctm_voiceai_write_report) while out_dir has no description anywhere. The description's 'output file paths' phrase only loosely gestures at out_dir, so it does not fully compensate for the coverage gap. A baseline 3 reflects partial 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?

States a specific verb and resource ('Returns the status of an analysis run') and enumerates the possible states (running/complete/error) plus the outputs returned. It is clear but does not differentiate from the close sibling ctm_voiceai_list_runs, leaving the agent to infer the per-run vs list distinction.

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 no explicit when-to-use or when-not-to-use guidance and never names an alternative. The conditional clauses ('when still running or failed', 'When complete') describe return behavior, not when this tool should be chosen over siblings, so the agent gets no routing help.

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 declare openWorldHint=true and destructiveHint=false, but the description adds real side-effect context the annotations don't: this writes files to disk, renders an HTML artifact, and opens a browser. It does not cover overwrite behavior or how out_dir is resolved, keeping it below 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 flow position and core action, then a compact input enumeration. The parameter list in sentence two is dense but each item earns its place by mapping to a distinct argument.

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 9-parameter tool with nested objects and no output schema, the description covers the primary inputs and the terminal write/render/open behavior well. It omits explanation of out_dir, account_id, and call_context, which is a notable but not crippling gap given schema coverage and the absence of an output schema.

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?

At 67% schema description coverage, the description usefully labels several parameters in prose (canonical topics, optional per-call table, reviewed agents with current instructions, recommendations Markdown, suggested rewritten prompt, browser open). It leaves out_dir, account_id, and call_context unmentioned, so it doesn't fully compensate for the 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?

States a specific multi-step action (writes analysis to files, renders self-contained HTML, opens browser) and situates it precisely as 'Step 6 of the review flow.' This clearly separates it from every sibling, which are auth, list, and read tools rather than a report terminal 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 'Step 6 of the review flow' framing gives strong sequencing context, and the second sentence enumerates exactly which inputs to pass. It does not name a when-not-to-use condition or an alternative tool, so it falls short of a 5.

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