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

With all four hint flags false, the description carries the burden of disclosing behavior. It does so by explaining the stateful nature of the operation: the gateway routes the answer to the pending visible prompt and reports the outcome. This adds meaningful behavioral context beyond the neutral annotations and implies the operation mutates interaction 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?

Three sentences with zero redundancy: purpose is front-loaded, the routing/outcome behavior follows, and the usage precondition closes. 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?

The tool is simple (one parameter) and has an output schema, so the description need not explain return values. It covers purpose, triggering condition, and post-invocation behavior. Only minor gaps remain, such as what happens when no pending interaction actually exists.

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 the single parameter is well-described ('The user's answer to the pending question'). The description's phrasing 'supplying the user's decision' echoes the schema without adding significant new semantic detail, so the baseline 3 is appropriate.

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

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

The description names a specific verb (resolve) and resource (exceptional question from TraeCN) plus the triggering context (the gateway could not handle it mechanically). This clearly differentiates it from siblings like traecn_send_message or traecn_decide_approval, which serve different interaction types.

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 an explicit precondition ('Only call when a pending interaction exists') and frames when it applies (questions the gateway cannot handle mechanically). It does not explicitly name which sibling tools are alternatives or when they should be chosen instead, but the pending-interaction gate is clear and actionable.

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 the description adds value beyond that by specifying what is and is not destroyed: the gateway records the cancellation and 'results already produced remain in task history.' It also discloses the return payload (task identity and post-cancellation status). This contextualizes the destructive nature usefully and does not contradict the annotations.

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, front-loaded with the primary purpose before the behavioral details. Each sentence earns its place — scope, behavior/side-effects, and return value. Slightly more verbose than strictly necessary to state the operation, but no wasted content.

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 cancellation tool with an output schema and provided annotations, the description is largely complete. It covers side effects (what stops, what persists) and the return shape. The only minor gap is the unstated relationship to traecn_stop_generation, which an agent might confuse it with given the sibling set.

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 the schema already documents taskId as the 'Stable task identifier returned by traecn_send_message.' The description only references 'by ID' and adds no new syntax, format, or provenance detail beyond the schema. At 100% coverage, the schema carries the burden, so a baseline 3 is appropriate.

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

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

States a specific verb ('cancel') and precise resource ('one gateway-tracked task by ID'). The mechanism of action — gateway stops shepherding at the next control point — further specifies the operation. This clearly separates it from siblings like traecn_get_task (read) and traecn_send_message (create).

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 conveys the effect (stops shepherding, retains results) and scope (single task by ID), which implies when it applies. However, it does not explicitly distinguish itself from the likely-overlapping sibling traecn_stop_generation, nor state any exclusions such as 'for a running generation use stop_generation instead.' The context is clear but the contrast with alternatives is left to inference.

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 this as a non-read-only, non-idempotent, non-destructive call. The description goes meaningfully beyond that by disclosing deferred allocation (conversationId=null, creationDeferred=true until first message) and the reuse-versus-create behavior for empty drafts, which an agent could not infer from annotations alone.

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 compact sentences, front-loaded with the purpose, followed by return behavior and the calling rule. Slightly dense phrasing ('until its first message') but no wasted sentences.

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 creation tool with an output schema, the description covers the one thing the schema cannot: the deferred-allocation lifecycle and draft-reuse rule. Complete enough to call correctly; only explicit sibling routing is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description's mention of conversationId/creationDeferred refers to outputs, not inputs.

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

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

States a specific verb and resource ('Prepare a fresh TraeCN conversation') plus the scoping condition ('genuinely new context'). It is clearly distinct from siblings like traecn_select_conversation or traecn_list_conversations, though it never names those alternatives 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?

'Call once per new context' gives a usage cue, and 'genuinely new context' implies not to call it when reusing an existing one. However, it never names the sibling to use instead (e.g. traecn_select_conversation) nor states explicit exclusions, leaving routing to inference.

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 flag destructiveHint=true and readOnlyHint=false, and the description expands on them: it reveals that approval revalidates expectedCommand, requires acknowledgeRisk and a locally recorded audit reason, and that denial requires only the decision. It also states the audit logging behavior and the 'never approve beyond scope' rule, which goes well beyond the annotations.

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 with no redundant phrasing. The first sentence states the core action, the second details the mechanics and caveat. Every clause earns its place; the most critical constraints are front-loaded.

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

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

With an output schema present and a complex 4-parameter decision tool, the description covers all necessary behavioral context: how to approve (with conditions), how to deny, and the authorization limit. It does not need to restate return values because the output schema exists, and the description leaves no obvious gaps for correct invocation.

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

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

Schema coverage is 100%, so the baseline for adding value is 3, but the description adds meaningful semantics: it explains why acknowledgeRisk and reason are required for approve, that expectedCommand must be the exact command returned with the pending interaction, and that denial only needs decision. This adds context beyond the schema's bare 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 specific verb ('Approve or deny') and a specific resource ('the unsafe or ambiguous command card currently visible in TraeCN'). It clearly distinguishes this tool from siblings: no other sibling handles approval or decisions, so its purpose is unambiguous. The phrase 'revalidates the exact expectedCommand' further pins down its 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?

The description states the condition for use ('unsafe or ambiguous command card') and gives a hard rule ('Never approve beyond the scope the user authorized'). It also clarifies that denial needs only a decision, implicitly indicating the minimal input for that path. It doesn't explicitly name alternative tools, but no sibling serves a similar decision role, so the guidance is sufficient.

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 flag destructiveHint=true and readOnlyHint=false, but the description adds valuable context: the deletion is permanent with no recovery, and it requires an explicit acknowledgement. It explains the consequence beyond the mere flag and reinforces the need for care, which adds behavioral transparency beyond annotations.

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 with zero redundant words. The primary purpose is front-loaded, followed by the required preconditions and consequence. 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?

For a destructive operation with three required parameters and an existing output schema, the description covers the essential aspects: what it does, what inputs are needed, and the irreversible consequence. It does not describe the response format, but the output schema likely handles that. Minor gap: no mention of what happens if the conversation is active (the description says 'inactive' but doesn't specify behavior for active ones), though the acknowledgement implicitly addresses deletion of inactive ones. Overall adequate.

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 restates the source of expectedTitle (from traecn_list_conversations), which reinforces the schema, but does not add new semantic meaning beyond what the parameter descriptions already provide. No extra context about format, timing, or side effects.

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 ('delete'), a clear resource ('inactive TraeCN conversation'), and a precise identifier mechanism ('by stable identifier'). It distinguishes from siblings like traecn_select_conversation and traecn_create_conversation, and adds qualifiers ('permanently', 'inactive') that make the 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?

It clearly specifies the required inputs (exact expectedTitle from traecn_list_conversations and an acknowledgement) and highlights the irreversible nature with 'no gateway recovery path.' It does not explicitly contrast with alternatives, but the conditionality is clear. Slight deduction for not stating a 'when not to use' scenario.

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 contributes the non-obvious behavioral constraint that repeated tight-loop polling is not the intended model. It also clarifies the payload difference between the two detail levels. It stops short of describing failure cases such as an unknown or expired taskId, which would be the natural remaining detail.

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, each carrying distinct information: what is returned, when to call it, and when not to. The exclusion is front-loaded with 'Not a progress primitive', which is the highest-value warning placed where it will be read.

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 an output schema present and annotations covering the safety profile, the description need not explain return values, and it correctly focuses on invocation timing and the polling pitfall. It is essentially complete for a simple two-parameter read, though it omits what happens when the task ID is unknown or how long a completed task remains retrievable.

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 both parameters are already documented at the property level, including the enum values and the default of "result"; the description only restates the 'trace' option in service of the diagnostic use case. That reinforcement is mildly useful but does not add new meaning beyond the schema, so the baseline 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?

"Read one known gateway task by ID" is a specific verb plus resource plus scope, and it immediately states what comes back (status plus final result, or the execution trace). That cleanly separates it from siblings like traecn_cancel_task and traecn_send_message, so an agent does not need to open the schema to know what this does.

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

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

It gives explicit positive triggers (once when notified of completion, once when resuming after a disconnect) and an explicit exclusion ("Not a progress primitive — do not poll in a tight loop"). That anti-pattern warning is exactly the guidance an agent needs, since polling is the most likely misuse of a task-status tool.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value beyond these by stating that the output identifiers are 'stable' and 'accepted by conversation-scoped tools,' which informs the agent about output usability. There is no contradiction with annotations.

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, tight sentence that front-loads the primary intent ('List the conversations') and packs in the scope, identifier property, and read-only nature. Every word earns its place; there is no fluff 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?

Given the tool's simplicity (no params, no side effects), the description covers the essential behavior: what it lists and why the identifiers matter. An output schema exists, so the description need not detail return fields. It could have mentioned that it reflects the 'current mode' but it does, so the context is sufficiently complete for an agent to use 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 tool has zero parameters, and schema description coverage is 100% (vacuous). Baseline for 0 params is 4. The description adds no parameter-specific semantics because none exist, but it does not need to. The absence of parameters is implicitly clear from the empty schema, and the description's mention of 'conversations available in the current TraeCN mode' reinforces what the output will contain.

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 action ('List the conversations'), the scope ('in the current TraeCN mode'), and the key feature ('stable identifiers accepted by conversation-scoped tools'). This distinguishes it from siblings like traecn_create_conversation or traecn_select_conversation, which perform different operations. The verb, resource, and differentiation are all explicit.

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 a clear usage context: 'call when choosing or verifying conversation context.' It implies this tool is for selecting or confirming conversations before using conversation-scoped tools. It does not explicitly name alternatives or state when not to use it, but the phrase 'choosing or verifying' provides sufficient guidance for an agent to decide when to invoke it over create/delete/select.

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 the safety profile is covered. The description still adds non-obvious behavior: that Auto can hide manual models and that this tool reports manualModelsHidden without mutating mode state. It does not say how the hidden case should be handled beyond reporting, which keeps it from a 5.

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

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

Three short sentences, each doing distinct work: what is returned, the Auto-mode edge case, and the call-ordering rule. The most decision-relevant information (what you get) is front-loaded and nothing is padded.

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 an output schema present, return-value details need not be spelled out, and the zero-parameter schema plus rich annotations mean little else is required. The only small gap is that it does not say whether the returned model names are the exact identifiers select_model expects.

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 no parameters, so there is nothing for the description to disambiguate; the baseline for a zero-parameter tool applies. No meaning is added or lost.

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

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

The description names a specific verb (list) and a specific resource (model names offered in the TraeCN UI) plus an extra output (the current selection). It is clearly distinguished from the sibling select_model, which performs a mutation rather than a read.

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 an explicit ordering rule: call this before select_model whenever model choice matters, naming the alternative tool and the condition that triggers it. The Auto-mode caveat also tells the agent to read the reported flag rather than trying to change modes, which is a concrete when-not behavior.

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 establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is already known. The description adds a relevant sequencing caveat and the "visible choices" framing, but it does not describe any additional behavioral constraints such as nonexistent label/section handling or empty choices; this is acceptable only because the output schema and annotations carry the rest.

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

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

One sentence packs the core operation, the identification method, the required predecessor, and a safeguard against inventing option values. It is front-loaded with purpose and contains 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 read-only listing tool with two well-described parameters, a provided output schema, and explicit dependency on prior list_settings/list_setting_sections calls, nothing else is required for an agent to invoke this 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?

Both parameters have full descriptions in the schema: label must exactly match list_settings output and section must exactly match list_setting_sections output. The description does not add more param-specific semantics beyond "identified by section and label," so the schema does the heavy lifting and no penalty or special credit 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 concrete verb and resource: "List the visible choices of one dropdown-style setting" and identifies the exact inputs needed (section and label). It also distinguishes this from the sibling tools list_settings and select_setting_option by scoping it to a single dropdown's choices.

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 this is "Required before select_setting_option" and warns "never invent an option value," which tells an agent exactly when to use the tool and what behavior to avoid. It does not enumerate all alternatives, but the dropdown-style scoping plus the requirement before select_setting_option makes the usage context clear.

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. The description adds meaningful context: it emphasizes the read-only discovery role before mutations and reinforces exactness of the section label. No contradiction, and it goes beyond the annotations by adding usage ordering and labeling caution.

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 with purposeful front-loading. The core purpose and the key usage constraint are both delivered with zero filler, making it easy for an agent to parse quickly.

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 read-only tool with an output schema and comprehensive annotations, the description covers purpose, usage, and the exactness requirement. Nothing an agent needs to invoke it correctly 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 description for the single 'section' parameter is complete (100% coverage) and already states 'exactly as returned by traecn_list_setting_sections'. The description reinforces this with 'never guess a label' but adds no new semantics beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (individual settings and their control types within one section), and ties the section to traecn_list_setting_sections, distinguishing it from sibling tools that list sections or options. The 'never guess a label' instruction further clarifies the exact task.

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?

Explicitly frames this as 'Read-only discovery preceding any setting mutation', giving a clear when-to-use. It also instructs 'never guess a label', implying the section parameter must exactly match a prior call. It does not explicitly name alternatives or exclusions, so slightly below 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?

Annotations already declare read-only, idempotent, non-destructive. The description adds the context that the list reflects what is 'currently visible' in the UI, indicating dynamic nature. This is additional context beyond the annotations, though it does not elaborate on return format or edge cases.

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 with no filler. The main action is front-loaded, followed by the critical usage requirement. Each 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?

Given the tool has no parameters, an output schema exists (not shown), and annotations cover safety, the description is complete for agent invocation. It states what it does and when to use it. The dynamic 'currently visible' hint is useful. Nothing an agent needs to call it correctly 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?

Tool has 0 parameters, so schema coverage is trivially complete. Baseline for 0 params is 4. Description adds no parameter-specific info, but none is needed. It clarifies the tool's purpose without parameter details.

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 ('List'), resource ('settings sections'), and context ('currently visible in TraeCN's settings UI'). Clearly distinguishes from sibling tools like traecn_list_settings and traecn_list_setting_options by focusing on sections. The phrase 'Required first step for any settings operation' reinforces its distinct 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?

Explicitly states when to use it: 'Required first step for any settings operation'. Provides guidance to never guess a section name, implying this tool is the source of truth. Does not name alternative tools, but it's clear that this is the entry point for settings operations.

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 a non-read-only, non-idempotent, non-destructive mutation, and the description adds a real behavioral fact beyond them: the tool verifies activation before returning, implying failure surfaces at call time rather than later. It leaves out what happens to a previously active workspace and whether the selection persists, which matters given idempotentHint=false.

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 tightly written sentences with the action and its verification guarantee first, followed by the usage trigger and the follow-up constraint. Nothing is redundant and nothing is buried.

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 an output schema present, return values need no explanation, and the description is sufficient for a one-parameter state-mutating call: what it does, when to call it, and the post-call convention. The only genuine gap is the fate of the prior active workspace and persistence semantics.

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 the single property already documents 'Absolute local folder path.' The description only reinforces the constraint that exactly one path is accepted ('one absolute local folder path'), adding minimal 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 supplies a specific verb ('Open'), a precisely bounded resource ('one absolute local folder path as the active TraeCN workspace'), and an outcome guarantee ('verify it became active before returning'). No sibling tool touches workspaces, so no disambiguation is owed, and an agent knows exactly what the call accomplishes.

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

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

It gives an explicit when-to-use trigger ('before submitting work that depends on a specific project') plus a downstream instruction not to repeat the path in the task message. There are no alternative tools to route to, and no explicit when-not-to-use case, so it falls just short of the top mark.

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 are all false, providing no safety or idempotency signals, so the description carries the burden. It discloses that the tool modifies state (makes active) and returns a confirmed identity, implying validation. This exceeds what annotations offer and gives useful behavioral context, though it stops short of describing error cases or side effects on other conversations.

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 with zero filler. The first sentence front-loads the core action and context, and the second states the return value. Every word contributes to understanding, making it appropriately concise 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?

For a simple selection tool with one parameter and an output schema (present), the description is largely complete: it states the action, the context, and the return. It implies the conversation must exist and gives confirmation behavior. It could mention failure modes or side effects, but for this complexity level it covers the essentials an agent needs to call 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 covers the single parameter fully with a clear description ('Stable identifier returned by traecn_list_conversations'), so the baseline is 3. The tool description adds no extra parameter meaning, but none is needed given the high coverage. The description's reference to 'existing conversation' reinforces the constraint without adding syntax details.

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: 'Make one existing conversation the active target for subsequent visible interaction.' It clearly distinguishes from sibling tools like traecn_delete_conversation or traecn_list_conversations by focusing on selection. The mention of 'subsequent visible interaction' adds context that this is a prerequisite for interactive actions, and the return statement clarifies the tool's 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?

The description provides clear context for when to use it: to set the active conversation for future interactions. It does not explicitly name alternatives or exclusions, but the purpose is self-evident and aligns with sibling selection tools like traecn_select_model. The phrase 'existing conversation' implies a prerequisite, offering implicit guidance on when it's applicable.

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 provide idempotentHint true and destructiveHint false. The description adds a useful behavioral detail: switching to the current mode is a no-op. It also mentions confirming the result, which is extra context. No contradiction with annotations.

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 deliver the core action, the output confirmation, and the usage condition without any fluff. The key instruction is front-loaded and 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?

Given a single parameter with full schema coverage and an output schema (presumably conveying the confirmed mode), the description covers the necessary aspects: what it does, when to call it, and the no-op edge case. 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 fully documents the 'mode' parameter with an enum and description (100% coverage). The tool description adds no additional parameter semantics beyond the no-op behavior, which is more about tool behavior than parameter meaning. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Switch') and names the exact resource and modes ('TraeCN between Solo and IDE mode'). It also adds the confirmation of the resulting active mode, fully distinguishing this tool from any sibling that deals with other aspects.

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?

Explicitly states the condition for invocation: 'Call only when the requested mode differs.' This gives clear direction on when to use the tool and implicitly when not to (when modes match), which is a precise usage guideline.

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 include idempotentHint=true, but the description adds the specific no-op detail and the important fact that it does not wait for model availability or capacity. This goes beyond the annotations, providing useful behavioral context without contradicting them.

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 with no filler. The primary action is front-loaded, followed by two concise behavioral notes. Every clause 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?

For a single-parameter tool with an output schema present, the description covers all essential operational aspects: the source of valid values, no-op behavior, and non-blocking execution. No critical information is missing for correct invocation.

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

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

Schema description coverage is 100% and the parameter 'model' is already described as 'Exact model name as returned by traecn_list_models'. The tool description reiterates this exact phrasing but offers no additional semantic value beyond what the schema provides. Baseline of 3 applies.

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

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

The description clearly states the action (select), the resource (model), and the exact source (from traecn_list_models). It distinguishes from siblings like traecn_select_mode (mode vs model) and list_models (list vs select) without ambiguity.

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 explicitly refers to traecn_list_models as the source of valid names, giving a clear prerequisite. It also notes the no-op behavior for the already-active model. However, it does not explicitly state when not to use it (e.g., when selecting a mode instead), though the name and context make that clear.

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 this is a non-read-only, non-destructive, non-idempotent mutation, and the description adds two real behavioral facts beyond them: invalid values are rejected (must come from traecn_list_setting_options) and the tool confirms the applied selection as a post-condition. It does not explain what happens on an invalid or stale value, nor whether re-selecting the same value has side effects, which matters given idempotentHint=false.

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, zero filler, with the core action front-loaded and the validity constraint immediately after. Nothing is repeated from the title or schema verbatim.

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 three-parameter mutation with full schema coverage, annotations, and an output schema (so return values need not be described), the definition covers action, precondition, and validation constraint. The remaining gap is error/staleness behavior and explicit sibling routing, both minor at this complexity.

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 all three parameters carry their own descriptions naming the exact source tool for each value. The description only reinforces that the value must come from traecn_list_setting_options, adding little beyond the schema. Baseline 3 applies when the schema already carries the semantic load.

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 (select) and resource (one previously listed option for a dropdown setting), plus the two-part identifier (section + label). It is clearly separable from siblings like traecn_set_setting_toggle, traecn_set_setting_text, and traecn_select_model, since it is scoped to dropdown-type settings.

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 a prerequisite workflow: the option must have been 'previously listed' and only values from traecn_list_setting_options are valid. That implicitly tells the agent to call the list tool first and names the alternative data source. It does not explicitly state when to prefer this over traecn_set_setting_toggle or traecn_set_setting_text, leaving the 'dropdown vs toggle/text' routing to inference from the word 'dropdown'.

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?

Beyond the annotations (readOnly=false, openWorld=true, idempotent=false, destructive=false), the description discloses that work is asynchronous/durable, that the gateway owns queueing, retries, recovery, and persistence, and that a taskId comes back immediately. It stops short of stating that each call creates a distinct task (relevant given idempotentHint=false) or any auth/rate-limit expectations, so it is strong but not exhaustive.

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 tightly written sentences, with the core action and return value front-loaded, followed by the usage rule and the anti-pattern. 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 two-parameter tool with full schema description coverage and an output schema, this is complete: the async contract, the return of taskId, and the correct follow-up behavior are all covered. Nothing needed to call it correctly 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 coverage is 100%, so the baseline is 3. The description adds real meaning: conversationId 'optionally' targets an existing conversation, implying that omitting it starts fresh work, and message is framed as the single instruction being delegated. That is a genuine semantic contribution over the schema's own 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 concrete verb+resource+outcome: 'Submit one user instruction to TraeCN as durable background work and return its stable taskId immediately.' It clearly delineates this from siblings like traecn_get_task (tracking) and traecn_cancel_task (aborting), so an agent can pick the right tool without reading schemas.

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

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

It gives explicit when-to-use ('Use this for every delegated coding request'), an optional targeting condition ('optionally targeting an existing conversation via conversationId'), and an explicit when-not-to ('Do not send follow-up messages to probe progress — track the returned task instead'), which routes the agent to the tracking sibling.

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=false, idempotentHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds a genuine behavioral trait beyond that: it writes exactly one value and then reads the field back to confirm its contents, which tells the agent the call is self-verifying. It stops short of describing overwrite semantics or what happens if the section/label does not resolve.

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 sentence with the action and its target front-loaded, followed by the post-write verification behavior. No filler, no redundant restatement of the tool name or title.

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 an output schema present, the description need not explain return values, and full parameter documentation is in the schema plus annotations cover the mutation profile. The remaining gap is failure behavior — missing section/label, or whether existing text is replaced — which is relevant for a non-idempotent write but not stated.

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 schema already ties 'label' and 'section' to the corresponding list tools. The description adds only the constraint that exactly one text value is written; it gives no format, length, or escaping guidance for 'text' beyond what the schema states. Baseline 3 is appropriate when the schema carries the parameter meaning.

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 target: 'Enter one text value into the setting field identified by section and label.' The phrase 'one text value' implicitly separates it from the toggle and option-setting siblings, but no sibling is named explicitly, so the differentiation is inferred rather than stated.

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

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

There is no explicit when-to-use or when-not-to-use guidance. The only routing hint is indirect: the field is addressed by section/label, which implies the list_settings / list_setting_sections discovery flow, but that dependency lives in the schema, not the description. Nothing tells the agent to prefer set_setting_toggle or select_setting_option in other cases.

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=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered; the description adds that the tool reads back the applied state, which no annotation conveys. The no-op sentence largely restates idempotentHint, and no failure mode (unknown section/label, missing workspace context) is described.

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, the mutation is front-loaded ahead of the post-condition, and no words are wasted. Every clause carries information an agent can act on.

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?

An output schema exists, so the 'read back the applied state' clause is sufficient without detailing return values, and all three parameters are fully documented in the schema. The remaining gap is error behavior for unknown or non-toggle settings, which matters for a 20-sibling settings surface but is minor at this complexity.

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

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

Schema description coverage is 100% and every parameter carries a cross-reference to the listing tool that supplies valid values, so the schema already carries the semantics. The description adds nothing about parameter values or how section and label are matched, leaving the baseline score appropriate.

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

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

The description states a specific verb pair (enable/disable) on a specific resource (one toggle setting identified by section and label), which implicitly distinguishes it from traecn_set_setting_text and traecn_select_setting_option. It never names those siblings explicitly, so the differentiation relies on the reader inferring 'toggle' means boolean-valued settings.

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

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

Usage is only implied through the prerequisites embedded in the schema ('exactly as returned by traecn_list_settings' / 'traecn_list_setting_sections'), which tells the agent to discover section and label first. There is no explicit when-to-use-this-vs-traecn_set_setting_text guidance and no stated conditions under which a setting cannot be toggled.

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 mark destructiveHint=true and readOnlyHint=false, but the description adds crucial context: the visible generation may belong to the user or another agent, and acknowledgeUntrackedWork=true plus an audit reason are required. It also scopes the action to only 'currently visible' output. This goes beyond the annotations with specific behavioral constraints.

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 with zero waste. The primary action is front-loaded, followed by the requirement and the alternative. Every clause carries meaning and the structure is easy to parse.

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 destructive action with an output schema, the description covers the essentials: what to stop, the prerequisite acknowledgment, and the preferred alternative. It doesn't explain what happens if no generation is visible or the outcome format, but the output schema likely handles that. The guidance is sufficient for an agent to call correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the meaning of acknowledgeUntrackedWork and reason, but adds no new information beyond what the schema already states. The conversationId is referenced as coming from traecn_list_conversations, which is helpful but already implied by the schema 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?

States the specific verb 'stop' and a precise resource: 'the generation currently visible in the named active TraeCN conversation.' It also distinguishes itself from the sibling traecn_cancel_task by explicitly saying to prefer that tool when a gateway task ID exists.

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?

Provides explicit when-to-use guidance: 'Stop only the generation currently visible...' and a clear alternative: 'Prefer cancel_task whenever a gateway task ID exists.' This leaves no ambiguity about which tool to select.

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