Server Quality Checklist

Tool Scores

• traecn_cancel_taskA
  3.9/5.0
  Behavior4/5

  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.

  Conciseness4/5

  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.

  Completeness4/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines3/5

  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.

• traecn_set_setting_toggleA
  3.9/5.0
  Behavior4/5

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

  The description adds value beyond annotations by noting the tool reads back the applied state and that applying the already-current state is a no-op. This complements the idempotentHint=true annotation and gives agents confidence about idempotent behavior. No contradictions with annotations were found.

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

  Conciseness5/5

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

  Two sentences, no fluff, and the core action is front-loaded. The idempotency note is a meaningful addition. Every phrase earns its place.

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

  Completeness3/5

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

  The description is adequate for a simple toggle tool with an output schema present. However, it does not explicitly state that this tool is only for toggle-style settings, nor does it reference sibling tools for non-toggle settings. Since the sibling list includes traecn_set_setting_text and traecn_select_setting_option, a brief routing note would improve completeness.

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

  Parameters3/5

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

  Schema coverage is 100% and each parameter is well-described with references to list functions. The description restates that section and label are identifiers but does not add new semantic detail beyond what the schema already provides. It does clarify that 'enabled' represents the desired toggle state, but that is very close to the schema's 'Desired toggle state.' Minimal added value.

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

  Purpose5/5

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

  The description clearly states the verb ('enable or disable'), the resource ('one toggle setting'), and the identifying mechanism ('section and label'). It also mentions reading back the applied state, which distinguishes it from sibling tools like traecn_set_setting_text and traecn_select_setting_option without ambiguity.

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

  Usage Guidelines3/5

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

  The description implies its usage for toggles but does not explicitly contrast it with alternatives. It does not state 'use this for toggle settings, not for text or option settings' or reference sibling tools. An agent may still infer correctly from the tool name and schema, but explicit guidance is missing.

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

• traecn_select_setting_optionA
  4/5.0
  Behavior3/5

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

  Annotations provide no hints (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description carries the burden of behavioral disclosure. It adds the key constraint that only values from traecn_list_setting_options are valid, which is useful. However, it does not disclose what happens on invalid input, whether the change is persistent, or any potential side effects beyond the confirmation. This is a moderate gap for a mutation tool.

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

  Conciseness5/5

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

  Two sentences with no redundancy. The core action and the critical constraint are both stated efficiently. The description is front-loaded with the verb and resource, and the second sentence adds the validation rule. It earns its place with no wasted words.

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

  Completeness4/5

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

  For a simple mutation tool with 3 parameters and an output schema present, the description covers the essential workflow (listing options first) and the validity condition. It relies on the schema for parameter origins, which is acceptable since the schema is rich. It does not detail error behavior or confirmation specifics, but those may be covered by the output schema. Overall, it is sufficiently complete for an agent to use correctly.

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

  Parameters3/5

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

  Input schema already covers all parameters with descriptions referencing the source lists (traecn_list_settings, traecn_list_setting_options, traecn_list_setting_sections). The description adds little beyond restating that the value must come from the list, which is already in the schema. With 100% schema coverage, the baseline of 3 is appropriate; the description does not introduce new parameter semantics.

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

  Purpose5/5

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

  The description states a specific verb ('Select'), resource ('dropdown setting'), and scope ('identified by section and label'). It also mentions confirming the selection, which adds clarity. This clearly distinguishes it from sibling tools like traecn_set_setting_toggle and traecn_set_setting_text, which handle different setting types.

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

  Usage Guidelines4/5

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

  The description implies a workflow: options must be 'previously listed' and only values from traecn_list_setting_options are valid. This clearly tells the agent to call the listing tool first. It does not explicitly name alternative tools or state when not to use this tool, but the 'dropdown setting' qualifier and the sibling context make the intended use clear enough.

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

• traecn_set_setting_textA
  4/5.0
  Behavior3/5

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

  Annotations already indicate this is a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds the behavior of confirming the field value afterwards, which is useful context beyond annotations. However, it does not disclose potential side effects like overwriting existing values or requiring the section/label to exist. The added confirmation detail earns a mid-range score.

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

  Conciseness5/5

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

  The description is a single, compact sentence that front-loads the action and key distinguishing detail ('one text value') and the confirmation step. No filler or redundancy; every word earns its place.

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

  Completeness4/5

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

  Given the tool's simplicity (3 required params, all documented) and the presence of an output schema, the description covers what an agent needs to invoke it correctly. It does not address error cases or prerequisites beyond the schema's exact-match instructions, but for this setting operation, the information is sufficient. Slightly more detail on the confirmation behavior or edge cases would push to 5.

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

  Parameters3/5

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

  Schema description coverage is 100%, so all three parameters are documented in the schema, including the requirement that label and section match exact values from listing tools. The description's mention of 'identified by section and label' reinforces this but adds no new information beyond the schema. Baseline of 3 is appropriate when schema covers all parameters.

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

  Purpose5/5

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

  The description clearly states the action: entering a single text value into a setting field, identified by section and label. It uses a specific verb ('enter') and resource ('setting field'), and the phrase 'one text value' distinguishes it from sibling tools like traecn_set_setting_toggle (toggle) and traecn_select_setting_option (selecting an option). The confirmation step also differentiates it from other setter tools.

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

  Usage Guidelines4/5

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

  The description implies usage for text-based settings, contrasting with toggles and option selectors among siblings. It does not explicitly state when not to use it or name alternatives, but the context is clear given the sibling tool names and the description's emphasis on 'text value'. This provides adequate but not exhaustive guidance.

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

• traecn_list_setting_optionsA
  4.1/5.0
  Behavior3/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• traecn_answer_questionA
  4.2/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• traecn_delete_conversationA
  4.2/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• traecn_select_conversationA
  4.2/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• traecn_list_modelsA
  4.3/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description's 'Read-only discovery' is redundant. However, it adds the specific detail that the tool returns the currently selected model alongside the list, which is beyond the annotations. This is useful behavioral context but not extensive.

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

  Conciseness5/5

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

  Two sentences, purpose-first, with no fluff. The essential usage hint is included without padding. Every word earns its place.

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

  Completeness5/5

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

  This is a simple, parameterless, read-only tool with an output schema. The description fully covers what an agent needs: what it returns and when to call it. Nothing is missing for correct selection and invocation.

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

  Parameters4/5

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

  With zero parameters and 100% schema description coverage, there is nothing for the description to add about individual parameters. The baseline of 4 for parameterless tools applies; the description makes no misleading claims.

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

  Purpose5/5

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

  The description clearly states the tool lists model names from the TraeCN UI plus the currently selected model. It uses a specific verb and resource, and the 'call before select_model' phrasing distinguishes it from the sibling selection tool.

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

  Usage Guidelines4/5

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

  It explicitly instructs to call before select_model whenever the model choice matters, giving clear context for when to use it. It doesn't list when not to use it, but the guidance is direct and actionable for a discovery tool.

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

• traecn_list_setting_sectionsA
  4.3/5.0
  Behavior3/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• traecn_select_modelA
  4.3/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• traecn_list_conversationsA
  4.4/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• traecn_stop_generationA
  4.4/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• traecn_create_conversationA
  4.5/5.0
  Behavior4/5

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

  Annotations already indicate non-read-only and non-idempotent, but the description adds clarity by stating that each call creates a new conversation and sets it as the active target. This is a useful behavioral disclosure beyond the annotations, without contradicting them, though it doesn't cover output format or failure modes.

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

  Conciseness5/5

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

  Three sentences, each serving a distinct purpose: the primary action, a usage caveat, and the return value. Front-loaded with the core purpose, no wasted words, and easy to scan.

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

  Completeness5/5

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

  For a zero-parameter tool with an output schema, the description covers everything needed: the action, side-effect, usage policy, and return information. An agent has all necessary information to invoke it correctly without further clarification.

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

  Parameters4/5

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

  The tool has zero parameters, so schema coverage is 100% and there is nothing to explain. Baseline of 4 applies, and the description does not need to compensate for any missing parameter details.

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

  Purpose5/5

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

  The description states a specific action ('create') and resource ('TraeCN conversation') and distinguishes it from siblings like select_conversation and list_conversations by focusing on creation and the 'active target' side-effect. It is immediately clear what the tool does and how it differs from similar tools.

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

  Usage Guidelines4/5

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

  Explicitly warns that every call creates an additional conversation and advises calling at most once per genuinely new context, which is strong usage guidance. It does not explicitly name alternatives, but the context implies when to use this versus selecting an existing conversation, leaving a small gap in exclusion guidance.

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

• traecn_list_settingsA
  4.5/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• traecn_open_workspaceA
  4.5/5.0
  Behavior4/5

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

  The description discloses that the tool verifies activation before returning, which is a meaningful behavioral trait beyond the annotations (all false). It implies a state change but does not detail failure modes or side effects. Given annotations provide little context, the description carries the burden and does a reasonably good job, though it could mention error handling or permissions.

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

  Conciseness5/5

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

  The description is two sentences long, front-loads the core action and verification, and includes the usage directive. Every sentence earns its place; there is no redundant or extraneous text.

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

  Completeness5/5

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

  For a simple tool with one parameter and an output schema, the description fully covers what the tool does, when to call it, and what to do afterward. It is sufficient for an agent to invoke it correctly without additional context.

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

  Parameters3/5

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

  The input schema already describes the single parameter as 'Absolute local folder path.' The description repeats this requirement without adding new semantic detail (e.g., format, examples, or constraints). With schema coverage at 100%, the description adds no additional parameter meaning, so the baseline of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the action (open), the resource (absolute local folder path), and the effect (becomes the active TraeCN workspace). It also specifies that the tool verifies activation before returning, making its purpose unambiguous and distinct from sibling tools that handle tasks, messages, settings, or conversations.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance on when to use the tool: 'Call before submitting work that depends on a specific project.' It also gives a practical follow-up instruction ('do not repeat the path inside the task message'), which is a clear usage directive. Although alternatives are not named, the tool's role as a workspace setup action is clear and no competing sibling exists.

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

• traecn_select_modeA
  4.5/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• traecn_send_messageA
  4.5/5.0
  Behavior4/5

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

  Annotations already indicate readOnlyHint=false, but the description adds meaningful behavioral context: it is durable background work, the gateway owns queueing, retries, recovery, and result persistence, and it returns immediately. This goes beyond what annotations convey and helps the agent understand the async nature and reliability guarantees. Not contradictory to annotations, and adds value beyond them.

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

  Conciseness5/5

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

  Two concise sentences with no filler. The first sentence states the core purpose and behavior (submit and return taskId, background work, gateway owns lifecycle), and the second gives usage guidance (use for every delegated request, optionally target conversation, do not probe). The key information is front-loaded and every phrase earns its place.

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

  Completeness5/5

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

  Given the tool's simplicity (2 params, 1 required), existing output schema, and annotations covering safety, the description is fully sufficient. It covers when to use, the async/durable behavior, how to handle the response (track the task), and the optional conversationId context. An agent has everything needed to invoke it correctly without further investigation.

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

  Parameters3/5

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

  Schema description coverage is 100%, so both parameters are already documented. The description adds a small amount of usage context, such as 'optionally targeting an existing conversation via conversationId,' but this is largely redundant with the schema description for conversationId. The description does not clarify any additional syntax or format beyond the schema, so a baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the verb (submit), the resource (one user instruction to TraeCN), and the outcome (return a stable taskId immediately). It also frames this as the primary tool for delegated coding requests, distinguishing it from sibling tools that track or cancel tasks. This is specific and unambiguous.

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

  Usage Guidelines5/5

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

  The description explicitly says 'Use this for every delegated coding request,' providing a clear when-to-use condition. It also warns against using it to probe progress ('Do not send follow-up messages to probe progress') and directs the agent to track the returned task instead, implicitly routing to the appropriate sibling (traecn_get_task). This is decisive guidance.

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

• traecn_decide_approvalA
  4.7/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• traecn_get_taskA
  4.7/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to repeat that. It adds the caution that this is 'not a progress primitive,' which prevents misuse. It also implies the trace level is for diagnosis, which is a behavioral context.

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

  Conciseness5/5

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

  The description is three sentences: the first states the core function, the second gives usage conditions, and the third adds a caution. It is front-loaded and every sentence earns its place without redundancy.

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

  Completeness5/5

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

  Given the output schema exists and covers return values, the description covers the essential aspects: what it reads, when to call, and how to request more detail. It also provides the anti-pattern (polling) guidance, making it complete for an agent to use correctly.

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

  Parameters4/5

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

  The schema already documents both parameters (taskId and detailLevel) with descriptions. The description adds that detailLevel 'trace' is 'for diagnosis' and clarifies that the default result returns 'status plus final result,' providing semantic context beyond the schema.

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

  Purpose5/5

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

  The description clearly states the verb 'Read' with a specific resource ('one known gateway task by ID') and explains the two modes (status+result vs. full trace). It distinguishes itself from siblings by implying it's a non-mutating read operation, which is unique among the listed tools.

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

  Usage Guidelines5/5

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

  The description explicitly instructs when to call: 'once when notified of completion or once later when resuming after a disconnect.' It also warns against polling: 'Not a progress primitive — do not poll in a tight loop.' This gives clear usage timing and alternatives.

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