Talkform

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the bar is lower, and the description still adds real value: it discloses the replacement behavior (existing endpoint is overwritten), that the signing secret is returned only once and is not retrievable later, and that a project API key is required. It stops short of describing failure modes or validation 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 short sentences, front-loaded with what is being configured, followed by mutation semantics, return value, and auth requirement. No filler and every clause carries 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 single-parameter mutation with no output schema, the description covers the destructive replacement, the one-time secret return, and the auth requirement, which is what an agent most needs before calling. Minor gaps remain around payload expectations and error behavior, but nothing critical 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?

With one parameter at 0% schema description coverage, the description supplies the only semantic constraint: the endpoint must be HTTPS, which is stricter than the schema's generic format:uri. The url parameter's purpose is otherwise self-evident from the resource description, so little more is needed.

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 ('configures') and resource ('one HTTPS endpoint for completed handoffs in this project'), scoping it to a single endpoint. That scope plus the get_webhook/delete_webhook siblings makes the distinction clear without opening any schema.

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

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

The description implies this is the way to set or change the endpoint (because it 'replaces any active endpoint'), but it never says when to prefer get_webhook or delete_webhook, nor states prerequisites such as having a prepared form or registered agent. Usage is inferable rather than 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?

Annotations already declare write, idempotent, openWorld and non-destructive; the description adds genuine context beyond them: a project API key is required, the call returns a private respondent link and shareText, and retries must reuse idempotencyKey. 'voiceEligible is true' is a dangling assertion with no explanation, which slightly muddies the behavioral picture.

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 sentences are mostly earning their place, but the ordering is scattered: return values, then config internals, then mode behavior, then auth, then retry, then an instruction not to invent answers. The fragment 'voiceEligible is true' adds noise rather than 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 a large nested input schema, no output schema and zero schema descriptions, the description should carry more. It covers the returned artifacts and a handful of config fields but omits much of the required field structure (field types, promptDetail, options), which an agent must infer from the raw 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?

Schema description coverage is 0% and the schema is deeply nested, so the description must compensate. It clarifies promptTitle, branding.fromName/purpose/logoUrl, theme hex colors and the mode default, but leaves required members like config.id, config.title, fields[].id/label/type/required/promptDetail entirely unexplained.

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 first sentence states a concrete verb and outcome: stores an interview and returns a private respondent link plus shareText. It is distinguishable from get_handoff/delete_handoff, though the name 'handoff' never reappears in the description, so the link between tool name and 'hosted interview' relies on the title.

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 real selection guidance: omitted mode creates a voice interview, set config.mode to text only for a written interview, and reuse the same idempotencyKey on retries. It does not say when to prefer this over sibling tools such as prepare_form or get_template, so the routing picture is incomplete.

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 and idempotentHint=true, so the description's job is to add context, and it does: it specifies the exact scope of destruction ('stored configuration and answers') and the auth/confirmation requirements. It stops short of stating irreversibility details beyond 'permanently' or what happens to already-retrieved results, so a 4 rather than 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, no filler, and the destructive consequence is front-loaded before the prerequisite. Every clause carries actionable 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 single-parameter destructive tool with strong annotation coverage and no output schema, the description covers consequence, scope, and access prerequisites. The only meaningful gap is that it does not connect the required 'id' to a handoff/interview record, though the tool name largely supplies that link.

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 0% description coverage and the description never mentions the single required 'id' parameter, so it adds no meaning about what the identifier refers to. The schema itself constrains the type to a UUID with a strict pattern, so the agent can still supply a value, but the description does nothing to compensate 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?

The description states a specific verb ('Permanently deletes') and the resources affected ('stored configuration and answers'), so the operation is unambiguous. It does not explicitly name the handoff/interview object from the tool name or title, and it does not differentiate itself from siblings like get_handoff or create_handoff, so 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?

The precondition 'Requires confirmation from the user and a project API key' implies when it is appropriate to call and gives an operational gate. However, there is no explicit when-not guidance and no reference to alternatives such as disabling rather than deleting, leaving the agent to infer the lifecycle decision.

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 and idempotentHint=true, so the safety profile is covered. The description adds real value beyond them by disclosing the destruction scope (pending deliveries are cancelled, not just future ones) and the auth requirement (project API key). It stops short of describing the response or behavior when no webhook exists.

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 action and its consequence, then the prerequisite. Every clause adds information and nothing is repeated from the title 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 zero-parameter destructive tool with no output schema, the description covers the action, the collateral effect on pending deliveries, and the auth requirement. Minor gaps remain around the no-active-webhook case and confirmation of the idempotent no-op behavior, which would matter for an agent retrying the call.

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 and the schema is empty with additionalProperties=false, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter semantics are needed.

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 (disables) and a scoped resource (this project's active webhook), plus the side effect of cancelling pending deliveries. The singular 'active webhook' also tells the agent this is not a per-webhook-ID operation, distinguishing it from get_webhook/configure_webhook.

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 teardown framing ('disables ... cancels pending deliveries') makes the use case clear, and the API-key prerequisite is stated. It does not explicitly contrast with configure_webhook (e.g. whether that also disables) or say what happens when no webhook is active, so it falls short of full when/when-not guidance.

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 readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds two genuinely new facts — the resource must be owned by the caller's project and a project API key is required — but says nothing about failure modes or what a returned handoff 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?

Two short sentences, no filler, and the resource scope is front-loaded. Brevity here is efficient rather than lazy, though it leaves little to work with.

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 no output schema, the description is the only place that could say what "checking" returns (status enum? form data? completion state?), and it doesn't. For a lookup tool the caller cannot predict the response shape 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?

One required parameter with 0% schema description coverage, and the description never mentions it. It is not stated whether `id` is the handoff ID or the underlying interview/session ID, which is exactly the ambiguity that sinks calls.

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?

"Checks a hosted handoff owned by your project" gives a verb and resource, but "checks" is vague — it doesn't say whether it retrieves status, details, or existence. The sibling get_result makes it unclear how a handoff differs from a result, and the description does nothing to separate them.

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 guidance on when to call this versus get_result, list_templates, or other read siblings. The only contextual statement is an auth prerequisite (project API key), which is useful but not usage 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?

Adds substantial context beyond the readOnly/idempotent annotations: the pending-state error behavior, a concrete rate-limit floor of 10 seconds, a 7-day expiry window, and an explicit negative ('No transcript is returned'). These are exactly the traits that would otherwise cause failed or misjudged calls.

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 short sentences, front-loaded with the return value, then failure mode, rate limit, expiry, and content boundary. Every sentence carries distinct operational information with no padding.

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 should convey the shape of 'completed structured answers' — it only says they are structured and lack a transcript. For a simple one-param read tool the failure/expiry guidance is strong, but the return payload and the id's origin remain underspecified.

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 0% and the single parameter 'id' is never explained in the description — it is unclear whether this is a handoff id, a template id, or a submission id, or where it comes from. With no schema documentation to fall back on, the description should have identified the id source, which is the one thing an agent could get wrong.

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 completed structured answers') and scopes it to a project, which distinguishes it from sibling read tools like get_handoff or get_template. It stops short of naming which sibling to use instead when the caller actually wants raw submission data.

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?

'Pending results return an error; poll no more often than every 10 seconds' gives concrete operational guidance on when this call will fail and how to poll, which is exactly what an agent needs before calling. No explicit alternative tool or prerequisite (e.g. 'after create_handoff') is named.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is clear. The description adds useful behavioral context by stating that the result is a public template returned as a structured, reviewable conversational form draft. It does not describe missing-template behavior or auth requirements, but the annotations reduce the burden.

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 definition is a single front-loaded sentence with no redundant or filler content. Every phrase contributes to the purpose and return format.

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-parameter read operation, annotations cover safety, and an output schema exists. The description adequately explains that it returns a structured template draft. Minor gaps remain around the id semantics and explicit distinction from list_templates, but nothing critical 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 schema has one parameter with enum values but 0% schema description coverage. The description mentions returning one public template but does not explain what the id parameter represents, how to choose between the enum values, or that only listed public templates are accepted. It does little to compensate for the schema 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?

The description states a specific verb and resource: returns one public template. The phrase 'one public template' also implicitly distinguishes it from list_templates. It does not explicitly name the sibling or contrast with prepare_form, so it falls short of full 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?

Usage is somewhat implied by 'reviewable' and the title 'Review a Talkform template,' suggesting it is for inspecting a single template. However, the description does not explicitly say when to use this tool versus list_templates or prepare_form, nor does it mention prerequisites or exclusions.

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, idempotentHint, and destructiveHint=false, so safety is covered structurally. The description adds value beyond that by disclosing a security detail not present in annotations — 'Signing secrets are never returned' — and by stating the API-key requirement. It stops short of describing delivery-metadata shape or how many recent deliveries are included.

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 with zero waste: return contents first, then the security exclusion, then the auth requirement. Each sentence carries information the agent needs and the phrasing is front-loaded with the payload.

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 no output schema, the description must describe the return value, and it does so at a high level ('active webhook metadata and recent delivery metadata'), plus the auth prerequisite and a security exclusion. It is slightly incomplete in not indicating the volume of recent deliveries or how 'active' is determined, but an agent has enough to call this 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?

This tool takes zero parameters, so the baseline is 4. The description correctly implies a no-argument call scoped implicitly to 'this project', and no parameter explanation is needed.

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 ('Returns active webhook metadata and recent delivery metadata for this project') and distinguishes the read operation from the sibling configure_webhook by the use of 'Returns' versus configuration. It does not explicitly name the sibling, so the differentiation is implied 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?

It states the authentication prerequisite ('Requires a project API key') which tells the agent under what conditions the call can succeed. However, it offers no explicit guidance on when to prefer this over configure_webhook or how it relates to delete_webhook; the read-versus-write split must 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?

The annotations already declare read-only, non-destructive, closed-world behavior. The description adds useful scope beyond that by specifying that only public templates are listed, which is an important visibility constraint for callers.

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 well-structured sentence with no filler. The core purpose and scope are front-loaded and immediately actionable.

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 zero-parameter schema, rich annotations, and existing output schema, the description is largely complete. It covers the essential purpose and scope, though it could explicitly mention that the result is a list of template summaries suitable for choosing one to retrieve via get_template.

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 there is no parameter behavior to document; the baseline for no-parameter tools is 4. The description appropriately avoids unnecessary parameter detail.

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: it lists public conversational-form templates. The scope ('public' and 'available for review') distinguishes it from retrieving a single template via get_template.

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 the tool is for browsing templates available for review. However, it does not explicitly state when to use this versus get_template or prepare_form, leaving the agent to infer that this is a discovery step before retrieving details.

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, so the safety profile is covered. The description adds valuable behavioral context by stating the tool 'Returns a draft without storing or publishing it,' which tells the agent this is a non-persistent preparation step, beyond what the annotations say.

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 sentences, front-loaded with the core purpose and followed by parameter clarifications and non-persistence behavior. No filler or redundancy; every sentence adds 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?

The tool is complex (9 parameters, nested objects, no schema descriptions) but benefits from an output schema and annotations covering safety. The description covers the core intent and non-persistence behavior, yet omits usage guidance and many parameter details, leaving important gaps for an agent to infer from the schema alone.

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% across 9 parameters, including nested fields, so the description must carry the burden. It clarifies key ambiguous parameters (promptTitle as the respondent-facing question, branding/fromName/purpose as origin identifiers, theme colors as hex values), but leaves several parameters like mode, title, fields structure, description, and instructions unexplained. Partial compensation with clear gaps earns a 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?

States a specific verb and resource: 'Turns interview questions into a validated, shareable form draft.' This clearly distinguishes the tool from sibling tools like configure_webhook or get_template, which handle different resources.

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 explains what the tool does but gives no explicit guidance on when to use it versus alternatives, no prerequisites, and no exclusions. The note about returning a draft without storing or publishing is behavioral context, not usage guidance.

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?

Goes well beyond the annotations (idempotent=true, destructive=false, openWorld=true) by disclosing the one-time secret reveal, that retries never expose it again, the 10 hosted handoffs/day quota, and that voice falls under shared realtime limits. These are exactly the operational facts an agent needs before calling a provisioning 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?

Four short sentences, front-loaded with what it creates and returns, followed by identity caveats, key handling, and quotas. No filler; every clause 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 no output schema, the description covers the important return value (the secret, returned once) and the limits an agent must respect. It is only slightly incomplete in not explaining 'name' or 'environment' effects and not describing failure behavior beyond idempotent retries.

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 0%, so the description must carry parameter meaning. It does so well for idempotencyKey (fresh UUIDv4, retry-safe) but says nothing about 'name' or the production/test 'environment' enum, leaving two of three parameters undocumented anywhere.

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 persistent machine-owned project') plus the key outcome ('returns its API key secret once'). The 'no email, sign-in, or human identity' clause distinguishes it from any human-signup flow, and no sibling tool overlaps this provisioning role.

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?

Implies the use case clearly (provisioning a non-human agent workspace) and gives operational guidance: use a fresh UUIDv4 idempotencyKey, save the secret, retries won't return it. It stops short of explicit when-not conditions or naming an alternative tool, so not a 5.

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