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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint:false. The description adds behavioral context by explaining the three comparison modes and the underlying API endpoint, which helps the agent understand the tool's side-effect-free nature and how the parameters influence behavior.

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

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

The description is concise and front-loaded with the primary purpose, followed by a clear bulleted list of modes. Every sentence earns its place, and the API endpoint is provided as a reference. No fluff.

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 has an output schema, so return format is covered there. The description fully explains the input combinations and the diagnostic purpose, making it complete for an agent to select and invoke correctly. Sibling relationships are not needed since this is a distinct comparison tool.

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

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

Schema coverage is 80%, so the baseline is 3. The description goes beyond the schema by synthesizing the parameter combinations (env-only, revision+running, revision+latest), clarifying the interplay between env, revision, and compare_with. This adds meaning beyond the individual parameter 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 clearly states the tool compares application configuration differences to diagnose configuration drift, with specific verb and resource. It also details three distinct comparison modes, distinguishing it from other tools in the sibling list that are primarily list/get/query operations.

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 explains when to use each of the three modes (only env, revision with compare_with=running, revision with compare_with=latest), providing concrete conditions. It does not explicitly mention exclusions or alternative tools, but the mode guidance is clear enough for an agent to decide.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the HTTP method (GET) and the categories of returned information, but it does not disclose additional behavioral traits like authentication needs, rate limits, or the effect of response_format. This moderate additional context, combined with strong annotations, justifies a 3.

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

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

The description is two short lines: a single sentence summarizing the purpose and the API endpoint. It is concise, front-loaded, and contains no irrelevant information, achieving perfect efficiency.

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 read-only tool with two parameters and an output schema, the description is fairly complete. It covers what the tool does, the detail categories, and the underlying API. It lacks explicit usage guidance and sibling differentiation, but given the annotations and output schema richness, it is sufficient for most cases. A perfect score would require more explicit context.

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

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

The schema provides minimal descriptions: app_name is just '应用名称' (application name) and response_format has an enum but no description. The description adds the URL template '/api/v1/applications/{appName}', clarifying that app_name maps to the path parameter. However, response_format is not explained, so with only 50% schema coverage the description only partially compensates.

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

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

The description clearly states the tool views application details and enumerates the included categories (basic info, policies, environment bindings, resource statistics). It also provides the API endpoint, adding specificity. However, it does not explicitly distinguish itself from sibling tools like vela_get_app_status or vela_get_application_manifest, though the level of detail implies it is the full-detail view.

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

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

There is no guidance on when to use this tool versus alternatives, such as 'use this for full details, use get_app_status for status only'. The description simply states what the tool does without any when/when-not criteria or exclusions, leaving the agent without explicit decision support.

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, and non-destructive behavior. The description adds context about the underlying compare API and the difference between latest and running states, which goes beyond what annotations provide. No contradictions found.

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 concise: two sentences plus an API reference. It front-loads the purpose and use cases, then explains source options, with no redundant or filler 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?

The tool has a rich output schema, thorough annotations, and a description covering purpose, use cases, source semantics, and API mapping. Everything needed for correct invocation is present.

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?

All parameters are fully described in the schema (100% coverage), and the description reinforces the meaning of 'source' with concrete semantics (latest vs running). The API reference adds extra clarity, making parameter usage well understood.

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

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

The description clearly states the tool exports the Application CR YAML manifest, using a specific verb ('导出') and resource ('Application CR YAML 清单'). It distinguishes from siblings like vela_get_application by targeting manifest export for GitOps/backup/audit use cases.

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 provides use cases (GitOps migration/backup/audit) and differentiates between source=latest and source=running. It doesn't explicitly name alternative tools, but the context is clear enough for an agent to know when to choose this 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, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds behavioral nuance by distinguishing between all-environment overview and per-environment detail, and includes the concrete API endpoints that shape expected behavior. It does not go into pagination or error modes, but the extra context is valuable 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?

The description is two short sentences: the first states the purpose and scope, the second lists the API endpoints. Every word earns its place, and the key information is front-loaded. There is no redundancy or 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?

Given that an output schema exists and annotations cover safety, the description is sufficiently complete for a read-only status tool. It clearly defines the two operational modes and maps to APIs. It does not mention authentication or rate limits, but these are not critical for a simple status read. The tool is well-specified overall.

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

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

Schema coverage is 67% (app_name and env have descriptions; response_format only has an enum reference). The description does not add parameter details beyond what the schema already provides, and the schema descriptions are adequate. The description's mention of '不填返回所有环境的状态概览' aligns with the schema's env description, but does not enhance it.

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 '查看' (view) and resource '应用运行状态' (application running status), and further clarifies scope with '全部环境概览或指定环境详情' (all environments overview or specific environment details). This clearly distinguishes it from sibling list tools like vela_list_applications and vela_system_info.

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

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

The description implies usage by describing the two modes (overview vs specific env) but does not explicitly state when to prefer this tool over alternatives or provide exclusions. Sibling tools are not referenced, so the guidance is implicit rather than explicit.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by exposing the underlying API endpoint and noting that the step name must come from record details, which implies a dependency on another resource. No contradictions 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 two sentences long, front-loads the purpose, and includes the corresponding API for reference. Every sentence earns its place with zero waste 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?

With an output schema present, the description need not explain return values. The tool is a straightforward read-only logs fetch, and the description covers its essential aspect (step dependency) along with the API endpoint. It is slightly terse but adequate for a tool in a well-structured context.

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

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

The input schema has 100% coverage for all four parameters, each with descriptive text. The description supplements this by explicitly highlighting that step is required and sourced from record details, and by showing the API's query parameter context. This adds useful meaning beyond the schema.

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

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

The description clearly states the tool's purpose: viewing logs for a specific step in a workflow execution record. It uses a specific verb+resource+scope structure (view workflow step logs) and is clearly distinct from all sibling tools, which are list/get operations for other entities.

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 a clear prerequisite: the step parameter is required and its name should be obtained from the record details first. While it does not explicitly name alternative tools, no siblings serve the same purpose, so the contextual guidance is sufficient. This is a clear usage context with a practical hint.

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, and non-destructive behavior. The description adds valuable context by mapping to specific API endpoints and clarifying the three modes of operation (list vs. enabled vs. detail/status). This goes beyond the annotations without contradicting them. However, it doesn't describe additional behavioral details like pagination, ordering, or potential large response sizes, so not 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?

The description is concise, using two sentences to convey the full scope. It's front-loaded with the main purpose and includes the relevant API endpoints as a bonus. No wordiness 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 list/detail tool with 5 optional parameters and an output schema, the description covers the primary modes and aligns with the parameters. It doesn't need to explain return values since an output schema exists. It could mention pagination or resource limits, but the core behavior is sufficiently described.

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

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

Schema description coverage is 80%, so baseline is 3. The description doesn't add much beyond what the schema already explains for each parameter. The mention of '单个插件详情与状态' aligns with the addon_name parameter, but it doesn't provide new semantic insights or usage examples for query, registry, or enabled_only.

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

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

The description clearly states the tool's purpose: viewing addon marketplace lists, enabled plugins, and individual addon details/status. It uses specific verbs ('查看' = view/list) and distinguishes this resource (addons) from sibling tools that handle other resources like applications, components, and environments.

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 this tool: for any addon-related query, with three distinct modes (marketplace list, enabled list, single addon detail). It doesn't explicitly name alternatives, but among the sibling tools, none cover addons, so the use case is unambiguous. Missing explicit exclusions or 'when-not-to-use' guidance, hence not 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the API endpoint and filter scope but reveals no further behavioral details like pagination, ordering, or result limits; this is acceptable given the annotation coverage.

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

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

The description is two short sentences, front-loaded with the action and resource. It is concise and every phrase carries relevant information, including API mapping and filter capabilities.

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 list operation with full annotations, an output schema, and self-describing parameters, the description is complete. It names the object, supported filters, and API endpoint, giving an agent everything needed to invoke correctly.

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

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

Schema description coverage is 100%, so every parameter (env, query, target_name, project_name, response_format) already has a meaningful description. The tool description summarizes the filter categories but does not add new semantics beyond the schema.

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

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

The description clearly states the action ('列出' = list) and resource ('KubeVela 应用'), and specifies supported filter dimensions and the corresponding API endpoint. This distinguishes it from sibling tools like vela_get_application (single-get) and vela_get_app_status (status).

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

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

The description gives clear context for when to use this tool: whenever a list of applications is needed, with optional filters by project, environment, target, or keyword. It does not explicitly state exclusions or name alternatives, but the list-vs-get distinction is implicit and supported by sibling tool names.

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

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

Annotations already cover read-only and non-destructive behavior. The description adds meaningful behavioral context by explaining that specifying cluster_name changes the response to a single cluster's details, and it includes the corresponding API endpoint. It 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?

The description is exceptionally concise: two short sentences that front-load the main action and then provide the minimal API mapping. Every word earns its place with no redundant 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?

The description adequately covers the tool's core purpose and dual-mode behavior, and an output schema exists to handle return values. However, it omits pagination semantics and the response_format option, which are relevant for an agent deciding how to invoke the tool effectively.

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 only 40%, and the description adds little parameter-level meaning beyond reinforcing cluster_name. Pagination parameters (page, page_size) and response_format are not explained in the description, leaving the agent to infer their behavior from defaults and schema structure alone.

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

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

The description clearly states the tool lists managed clusters and, when cluster_name is provided, returns detailed resource information for that cluster. It uses a specific verb plus resource and distinguishes this from sibling list tools like vela_list_applications.

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 two primary usage modes: list all clusters when no cluster_name is given, and view a specific cluster's details when it is supplied. It does not explicitly name alternatives or exclusions, but the tool's uniqueness among siblings makes the 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?

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the dual behavior (list vs. detail) and the API path, but does not elaborate on formats, pagination, or error behavior. This is modest supplemental context beyond annotations, warranting a score of 3.

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

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

The description is two sentences, front-loaded with the primary action (list components), and includes a succinct summary of the conditional detail mode and the API endpoint. Every word contributes, with no redundancy or excessive detail.

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

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

Given that an output schema exists (as per context signals), the description need not explain return values. It adequately covers the tool's dual purpose and provides a reference to the API. The slight gap is that it does not mention the 'env' parameter's list-only effect, but that is already in the schema. Overall sufficient for the tool's 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 high (75%+), and each parameter already has a description in the schema (e.g., 'component' notes it returns details including properties/traits). The tool description reinforces the component behavior but adds little beyond the schema. Thus the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: listing application components, and when a component is specified, returning its details (properties, traits, definition). It also gives the corresponding API endpoint, making the scope explicit and distinguishing it from sibling tools like get_application or list_applications.

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 the tool: for listing components or retrieving a specific component's details. It does not explicitly state when not to use it or name alternatives, but the conditional behavior ('指定 component 时') gives a usage pattern. No exclusion criteria are mentioned, so it fits 'clear context, no exclusions'.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds context by noting that specifying definition_name returns the parameter schema and by providing the exact API endpoint, which goes beyond the basic safety profile.

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 remarkably concise: two sentences that front-load the core purpose and follow with the API reference. Every word earns its place with no 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 read-only listing tool with an output schema and good annotations, the description covers all essential aspects: what it lists, how to get details, and the underlying API. No critical information is missing.

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

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

Schema description coverage is high (75%), so the baseline is 3. The description enhances param understanding by explaining that definition_name triggers schema return and by mapping the definition types to Chinese labels, adding meaningful semantic context.

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

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

The description clearly states the tool's function: viewing component/trait/policy/workflow step definitions, with the added behavior of returning a parameter schema when a definition name is specified. This distinguishes it from sibling tools that operate on applications, components, or projects.

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

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

The description implies usage for listing definitions and retrieving schemas via the API mapping, but does not explicitly state when to use this tool versus alternatives or mention any exclusions. Sibling tools are not referenced, so the usage context is only implied.

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, covering most safety behavior. The description adds the specific API endpoint and environment scoping, but does not disclose pagination behavior, default page size, or how the response is structured beyond the schema. Meets baseline but adds limited value.

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 consists of two concise sentences: one for the purpose and one for the corresponding API. It is front-loaded, contains no redundant text, and every word adds value.

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

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

The description provides the core function and API mapping, which is helpful. However, with 5 parameters and pagination, it could mention that results are paginated or that page_size applies. Given the presence of an output schema, return values need not be described, but the description still feels minimal for a complete context.

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

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

Schema description coverage is only 40% (only app_name and env have descriptions). The tool description does not elaborate on any parameters, especially page, page_size, and response_format, which are left without descriptions in the schema. It fails to compensate for the low coverage, leaving agents unclear about pagination and output format semantics.

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

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

The description clearly states the tool's purpose: '查看应用在指定环境的部署记录' (view deployment records of an application in a specific environment), with an explicit API mapping. It is specific about verb and resource, but does not explicitly differentiate from sibling list tools like vela_list_workflow_records.

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

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

There is no guidance on when to use this tool versus alternatives. The description simply describes the function and API, offering no context for selection, exclusions, or references to other tools that might be more appropriate.

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, so the safety profile is covered. The description adds the API endpoint and the fact that associated delivery targets are included in the response, which is useful behavioral context 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?

The description is extremely concise: two short sentences (one describing the action, one listing the API). It is front-loaded with the core purpose and contains no unnecessary words.

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

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

For a simple list operation with strong annotations and an output schema, the description covers the core purpose, the API mapping, and the extra detail about associated delivery targets. It does not explicitly mention pagination or project filtering, but these are documented in the schema. Overall, it is sufficiently complete for typical use.

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 description does not explain any of the parameters. Schema description coverage is only 25% (only project_name has a description). Page, page_size, and response_format lack descriptions, and the tool description does not compensate for this gap. Parameter names are somewhat self-explanatory, but the coverage is too low.

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

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

The description clearly states the tool lists environments and their associated delivery targets, using a specific verb (list) and resource (envs). It also provides the API endpoint, which further clarifies the exact purpose and distinguishes it from sibling tools like vela_list_targets.

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 does not provide any guidance on when to use this tool versus alternatives. There is no mention of filtering, prerequisites, or exclusions. It simply states what it does without contextualizing use cases or referencing similar list tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is clear. The description adds only the API endpoint and use case, not additional behavioral traits like pagination limits or result ordering. Since annotations carry the burden, a 3 is appropriate.

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

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

The description is two short sentences, perfectly sized and front-loaded with the primary action. Every sentence adds value, including the API reference and usage context.

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 read-only list tool with pagination params and an output schema, the description is sufficient. It explains the use case and provides the API endpoint, while annotations and schema cover safety and parameters. It does not explain pagination behavior, but that is already in the schema.

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

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

Schema description coverage is 100%; all three parameters (page, page_size, response_format) have descriptions in the schema. The tool description itself does not add parameter-level meaning, so the baseline of 3 is correct.

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

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

The description clearly states the tool lists projects in the platform with a specific verb and resource, and adds the use case 'before creating an application to confirm available projects.' This effectively differentiates it from sibling tools that list other entities like users or applications.

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

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

It provides clear context: use this tool before creating an application to confirm available projects. While it doesn't explicitly name alternatives or say when not to use it, the use-case guidance is sufficient and directly tied to the tool's purpose.

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 the API endpoint and the purpose (pre-deployment validation) but no additional behavioral traits like pagination or response structure. With annotations present, this is adequate but not enriched.

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

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

The description is two sentences, front-loaded with the main action, and includes the API endpoint as supplementary info. Every sentence earns its place, with no redundant or verbose text.

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 read-only list tool with annotations covering safety, an output schema present, and all parameters documented, the description is sufficient. It states purpose, usage context, and API reference. Slight deduction for not mentioning that results are specifically for the given project, though this is implied by the resource scoping.

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%: both project_name and response_format have Chinese descriptions in the schema. The description adds no extra parameter semantics beyond restating the tool's purpose. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description clearly states the tool lists available delivery targets for a specified project, using a specific verb ('列出') and resource ('项目可用的交付目标'). It differentiates from sibling tool vela_list_targets by explicitly scoping to a project, and mentions the use case (pre-deployment validation).

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 the tool: '部署前确认目标合法性' (confirm target legality before deployment). However, it does not explicitly mention alternatives or exclusions, such as comparing with vela_list_targets which lists targets globally without project scope.

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 and destructiveHint=false, so the safety profile is covered. The description adds the API endpoint and troubleshooting purpose, but no additional behavioral traits like pagination or authentication requirements, so it does not go beyond the annotation baseline.

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: the first states purpose and use case, the second gives the API path. No redundant information, well 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?

For a simple read-only list tool with output schema and strong annotations, the description covers the core purpose, use case, and API reference. Minor gap: response_format is not explained, but the overall context is sufficient for an agent to select and invoke the tool.

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

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

Schema coverage is 50% with project_name described but response_format not. The description only mentions the project name in passing and does not explain the response_format parameter or its possible values, so it compensates poorly for the low coverage.

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

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

Description clearly states the tool lists members of a specified project and their roles, with a specific verb and resource. It also distinguishes itself from sibling tools like vela_list_projects and vela_list_project_targets by focusing on project users.

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 tool is for troubleshooting permission (403) errors, giving clear context for when to use it. It does not mention when not to use it or alternative tools, but the use case is sufficiently 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. However, the description adds only the use case and API endpoint, offering no additional behavioral traits such as result ordering, pagination behavior, or response contents.

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 consists of two short sentences that are front-loaded with the primary purpose. Every sentence contributes useful information (purpose, use case, API mapping) with no redundancy.

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

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

The tool is a simple read-only list operation with rich schema (83% coverage), an output schema, and safety annotations. The description adequately covers the core use case and API mapping; no critical missing information is evident for an agent to select and invoke 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?

Schema description coverage is 83% (above 80%), so the baseline is 3. The description does not explain parameters, but the schema already documents app_name, env, status, page, page_size, and response_format is a self-explanatory enum.

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

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

The description clearly states the tool's function with a specific verb ('查看' - view) and resource ('应用版本（revision）历史'). It also adds a use case ('可用于回滚前确认目标版本') and distinguishes from sibling tools like vela_list_deploy_records by focusing on revision history.

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 provides a usage context: '可用于回滚前确认目标版本' (can be used to confirm target version before rollback). This gives clear guidance on when to use the tool, though it does not mention exclusions or alternative tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the API method (GET) and clarifies the target definition, but it does not disclose pagination behavior, response format nuances, or any other operational details. Since annotations cover the key behavioral traits, a score of 3 is appropriate.

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

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

The description is extremely concise—two sentences that state exactly what the tool does and the corresponding API. No redundant words, no filler. It earns a top score for efficiency and front-loading.

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

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

Given that this is a straightforward listing tool with an output schema and strong annotations, the description is minimally adequate. It defines the resource and API, and the output schema covers return structure. However, it lacks usage guidance and parameter explanation, and does not differentiate from sibling tools, leaving some gaps for a fully contextual understanding.

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 description does not mention parameters at all. Schema coverage is only 25% (only project_name has a description), so the description should compensate by explaining parameter meanings, but it does not. The agent must rely solely on the schema's sparse descriptions and defaults, leaving page, page_size, and response_format ambiguous.

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

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

The description clearly states the tool's purpose: listing delivery targets, and defines 'target' as a cluster+namespace combination. It also gives the corresponding API endpoint, adding specificity. However, it does not distinguish itself from the sibling tool 'vela_list_project_targets', so it falls short of a 5.

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

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

No guidance is provided on when to use this tool versus alternatives. The description does not mention any prerequisites, exclusions, or why one would prefer this over 'vela_list_project_targets' or other list tools. This leaves the agent without decision support.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond annotations: it discloses that the response includes tokens and that the tool can be used to construct trigger addresses, plus the corresponding API endpoint.

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

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

The description is extremely concise, consisting of two short sentences. It is front-loaded with the primary purpose and includes the API endpoint as a secondary note. Every word earns its place with 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?

For a simple list tool with rich annotations and an output schema, the description is mostly complete. It covers the core function and a key output detail. However, it leaves the response_format parameter unexplained, which is a minor gap given the schema also lacks a description for it.

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 50%: only app_name is described, while response_format is not. The description does not compensate for the undocumented response_format parameter, nor does it add any parameter-level meaning beyond what the schema provides. It does not explain how the parameters affect the call or output.

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

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

The description clearly states the tool lists an application's webhook triggers and even mentions that the response includes tokens for constructing trigger URLs. This specific verb+resource clearly distinguishes it from sibling list tools like vela_list_components or vela_list_revisions.

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 no guidance on when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. It only states what it does and the API endpoint, leaving the agent to infer usage context from the tool name.

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?

注解已声明只读、幂等、非破坏性，描述额外补充了条件式返回行为（工作流列表/记录/详情）及“含各步骤状态，可据此取日志”的用途，增强了行为透明度。虽未提及分页或认证，但在注解覆盖安全特性的前提下，描述已提供重要上下文。

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?

描述极简，采用分号分隔条件逻辑，并附上对应 API 的 URL 模板，信息密度高且结构清晰，没有冗余内容。

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?

对于这种条件组合查询工具，描述完整覆盖了三种调用层级和返回内容（含步骤状态），并关联日志获取用途。存在输出 schema 时无需赘述返回格式，描述足以帮助 agent 正确选择工具并构造参数。

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 覆盖率为 50%，描述对关键参数 workflow_name 和 record 的条件语义进行了补充，解释了不填和填写时的行为差异。这超出了 schema 本身的信息，弥补了覆盖率不足。但 page、page_size、response_format 未在描述中说明，因此未给满分。

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?

描述以“三合一查询”开篇，明确说明工具的核心功能：根据是否填写 workflow_name 和 record 分别列出工作流、执行记录或执行详情。具体动词“列出”和资源（工作流/记录）清晰，且与兄弟工具如 vela_get_workflow_logs 形成区分。

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?

描述提供了明确的按条件使用场景：不填 workflow_name 列出工作流，填 workflow_name 列出执行记录，再填 record 获取详情。虽然没有显式给出“何时不使用”或替代工具，但上下文清晰，足以指导 agent 根据参数选择用途。

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safe read-only nature is known. The description adds the exact API endpoint (GET /api/v1/system_info) and a clear description of the returned data categories, reinforcing the read-only behavior without contradiction.

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

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

Three concise lines: resource and content, recommended use case, and API endpoint. No filler, no redundant restatement of the name, and important information is front-loaded.

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

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

Given low complexity, robust annotations, and an output schema, the description is complete. It states the resource, the exact API, the kind of information returned, and a practical usage scenario. No critical behavioral or prerequisite details are missing for a read-only system info tool.

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

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

The single optional parameter response_format is fully described by the input schema with an enum of markdown/json and a default of markdown. The description does not mention it, but since the schema provides complete semantics, no additional compensation is required. The schema coverage is 0%, but the parameter is self-explanatory.

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?

Description states a specific verb '查看' (view) and a clear resource 'VelaUX 平台系统信息', enumerating contents like KubeVela version, login method, cluster/app stats, and enabled plugins. This clearly distinguishes it from sibling list/get tools that target individual entities.

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

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

It provides an explicit use case: '适合作为接入新环境后的连通性与版本自检' (suitable as a connectivity/version self-check after onboarding a new environment). It does not mention alternatives or exclusions, but the context is specific enough for an agent to identify when this tool is appropriate.

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 and idempotentHint=true, covering the safety profile. The description adds meaningful behavioral detail: '错误以结构化文本返回, LLM 可直接 parse 修复后重试' and that the server assembles the velaql string, which informs error recovery and invocation expectations. 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 two sentences with a clear lead action, API endpoint, usage pattern, and error-handling note. Every sentence adds distinct value with no filler or repetition.

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

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

For a tool with a view enum and nested params, the description plus rich schema/annotations covers the essential context: what it does, how it works, and error recovery. It doesn't enumerate all views, but the schema does, so the description is sufficient for selection and invocation.

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

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

The tool description itself only points to 'ParamSchema' descriptions and does not explain parameters, but the input schema provides detailed per-view key mappings (75% coverage). The schema carries the semantic burden, so the description adds little beyond the pointer, keeping this at the baseline 3.

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

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

The description opens with '执行 VelaQL 查询' and lists concrete runtime data examples (Pod list, container logs, resource topology), clearly defining the tool's function. It also cites the exact API endpoint (GET /api/v1/query?velaql=), which helps distinguish it from sibling resource-listing tools.

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

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

The description explains the query mechanism (view enum + structured params, server-assembled VelaQL) but does not explicitly state when to prefer this tool over sibling list/get tools, nor does it provide exclusions. Usage is implied rather than explicit, so guidance is present but not fully fleshed out.

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