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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context by disclosing that credential fields are masked (凭据字段已脱敏) and that the full configuration is returned. This goes beyond what annotations provide.

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 core purpose and a security note. Every word contributes value, with 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?

For a simple single-parameter GET-like tool with strong annotations and no output schema, the description adequately covers what the tool does and a key behavioral nuance. It states the resource, scope, and a privacy-relevant detail, which is sufficient for the tool's simplicity.

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% for the single parameter 'username', and the schema describes it as '消费者 username'. The description does not add additional parameter semantics beyond what the schema already provides, 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.

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

The description uses a specific verb (查询/query) with a clear resource and scope (单个消费者的完整配置/complete configuration of a single consumer). This clearly distinguishes it from sibling tools like apisix_list_consumers and other get_* 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 implies its use case by specifying '单个消费者' (single consumer), which contrasts with list operations. However, it does not explicitly state when-not-to-use or name alternative tools, so it falls short of a 5.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context that the schema is version-sensitive and may differ from expectations (e.g., 'disable' moved into '_meta'), which informs the user about the dynamic nature of the output beyond the static hints.

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 no waste. The first sentence states the core function and return content, the second provides rationale for using the tool. Every sentence earns its place, and it is properly 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 the tool's simplicity (one parameter, clear purpose) and rich annotations, the description covers the essentials. It does not describe the exact output format, but for this type of query tool, the provided detail is sufficient. It could be slightly more explicit about the response shape, but is not critically incomplete.

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

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

Schema coverage is 100%, and the parameter description already provides an example ('如 key-auth、proxy-rewrite'). The tool description adds no additional semantic information about the parameter, so the baseline of 3 applies.

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

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

The description clearly states the tool queries a single plugin's schema, listing specific contents (field definitions, types, required fields, defaults, metadata_schema, consumer_schema). This distinguishes it from sibling tools that operate on routes, services, or other resources, making the purpose unmistakable.

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 implicitly explains when to use this tool by noting that APISIX plugin fields vary across versions and that real schema is better than hard-coded rules. This provides clear context for usage, though it does not explicitly name alternative tools or exclusions.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the configuration is returned complete without trimming or truncation, which gives useful behavioral context about output fidelity. However, it does not describe errors, authentication, or pagination 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 a single sentence that immediately states the tool's purpose and a key behavioral guarantee. Every phrase adds value, with no wasted words.

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

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

For a simple get tool with one parameter and rich annotations, the description is sufficient. It names the resource, specifies what is returned (complete configuration), and differentiates from list tools. It does not cover error cases, but given the openWorldHint, this is acceptable.

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

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

The schema description coverage is 100%, with the 'id' parameter described as '路由 ID' (route ID). The description does not provide additional parameter details beyond the schema, so it meets the baseline of 3 for high schema 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?

The description uses the verb '查询' (query) and specifies the resource as '单个路由' (single route), clearly distinguishing from sibling list tools like apisix_list_routes and other get tools. The phrase '完整配置（不裁剪、不截断）' further specifies the scope and output property.

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 retrieving a single route's full configuration, but it does not explicitly state when to prefer this over apisix_list_routes or other get tools. No alternatives are mentioned, 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 readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable context beyond annotations: the response is from the mcp-apisix client's probe, includes format version and capability list, and explicitly notes the Admin API lacks node info endpoints. This enriches behavioral understanding without contradicting 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 concise and well-structured: it front-loads the primary purpose, then clarifies what the response is and is not, and ends with the practical usage. Every sentence adds value, with no redundancy or wasted words.

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

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

Given no output schema and no parameters, the description carries the full burden of explaining the return value and context. It specifies that the return includes response format v2/v3 and an available capability list, and clarifies it is not runtime info. This is sufficient for an agent to understand and use the tool correctly.

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

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

The tool has zero parameters and schema coverage is 100%, so the baseline is 4. The description does not need to add parameter semantics, and it appropriately focuses on the return value and purpose instead.

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: '查询客户端探测层状态' (query client detection layer status), specifying it returns response format v2/v3 and a capability list. It distinguishes itself from sibling tools by clarifying it returns MCP client probe results, not APISIX node runtime info, which is a unique scope.

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 when-to-use context: '用于判断分页/过滤/校验等能力是否可用' (used to determine if pagination/filtering/validation capabilities are available). It also states when-not-to-use by explaining it is not APISIX node runtime information. However, it does not explicitly name alternative tools, so it falls short of a 5.

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

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 known. The description adds 'complete configuration' as return scope, but does not elaborate on behavior beyond that. No contradiction with annotations.

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

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

The description is a single, compact sentence in Chinese that conveys the core purpose without unnecessary words or repetition. It is well-structured and 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 get-by-ID operation, the description, combined with informative annotations and a complete schema, is fully adequate. It states the key outcome (complete config) and no additional context is needed.

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

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

The schema covers 100% of the parameter details, including the 'id' description '服务 ID'. The tool description adds no extra parameter semantics beyond implying the resource type, 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.

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

The description '查询单个服务的完整配置' clearly states the verb (query), resource (single service), and scope (complete configuration). It distinguishes from siblings like list operations by emphasizing 'single' and 'complete configuration'.

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 usage is implied rather than explicit. It suggests retrieving a single service's config but does not explicitly mention when to use it over listing tools or provide exclusions. No alternative tools are named.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds the context that it returns the '完整配置' (complete configuration), which is useful beyond what annotations state. No additional behavioral details like error handling or permissions are provided, but the annotation coverage lowers the burden.

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

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

The description is a single, concise sentence in Chinese that is front-loaded with the action and resource. There is no redundant information 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?

This is a simple read tool with one parameter, strong annotations, and no output schema. The description adequately states the tool's purpose and that it returns the full config. A minor gap is the lack of mention about behavior when the ID does not exist, but overall the description is sufficient for a low-complexity 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 100% with the 'id' parameter described as '上游 ID'. The tool description does not add any further meaning beyond the schema, so the baseline of 3 applies as the schema carries the full parameter documentation.

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 queries a single upstream's complete configuration, using the verb '查询' and resource '单个上游'. It distinguishes from list_upstreams by specifying '单个' (single), but does not explicitly differentiate from other get_* siblings in the same family.

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

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

Usage is implied: the description says it queries a single upstream, so use this when you need one upstream's config instead of listing all. However, it does not explicitly state when to use this vs alternatives like list_upstreams or get_service, nor provide any exclusion criteria.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read. The description adds the important disclosure that credential fields are masked (plugins subtree), which is beyond annotation and helps set expectations about response data. No contradiction with annotations.

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

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

Two concise sentences: first states the action, second provides a critical caveat about masked secrets. 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 read-only list tool with well-documented parameters and safety annotations, the description covers the main purpose and an important behavioral note. It doesn't detail return structure or pagination, but the schema handles parameters, making it adequately complete.

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% with detailed descriptions for all four parameters (page, detail, fields, page_size). The description does not add parameter-specific semantics beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states '查询消费者列表' (query consumer list), specifying the verb and resource. It distinguishes from sibling tools by targeting the consumer resource specifically, and the masking note adds context without confusing the purpose.

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

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

There is no explicit when-to-use guidance or alternatives mentioned. The purpose is implied by the tool name and description, but it doesn't differentiate from apisix_get_consumer or other list tools. Thus it relies on the agent to infer usage.

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, openWorldHint, and non-destructive behavior. The description adds the context that the resource count is small, which is a mild behavioral insight, but it does not disclose return format or pagination behavior. No 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?

The description is two short sentences, front-loaded with the main action. Every word contributes to the purpose or design rationale, 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 simple list tool with rich annotations and fully described schema, the description covers the essential purpose and design rationale. It lacks explicit comparison to other list tools, but that is not critical given the clarity of the resource name.

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 has 100% coverage with descriptions for all four parameters (page, detail, fields, page_size). The description adds no parameter-specific semantics, so the baseline score of 3 applies.

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

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

The description directly states '查询全局规则列表' (query global rules list), a specific verb+resource. It also explicitly notes the deliberate absence of a get tool, distinguishing this tool from sibling resources that do have get 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 that no get tool is provided because resource count is small and list suffices, implicitly guiding the agent to use this list tool rather than searching for a get tool. However, it does not explicitly compare with other list tools for different resources.

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

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

注解已声明 readOnlyHint=true、idempotentHint=true、destructiveHint=false，安全属性清晰。描述补充了'有意不提供 get 工具'这一行为约束，但未披露分页、返回结构等操作细节，在注解基础上增益有限。

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?

描述非常简短，第一句直接点明用途，第二句虽简短但信息有些含糊（'有意不提供 get 工具'）。整体无冗余，但第二句价值有限，且结构上未按重要性排序。

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，描述未说明返回格式、分页行为、插件配置的具体含义，也未与 list_plugins 等相区分。对于带分页的列表工具，仅靠当前描述和注解不足以让代理完整理解工具边界和调用结果。

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=100%，按规则基线为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?

描述明确说明'查询插件配置列表'，动词+资源清晰，但未与同类列表工具（如 list_routes、list_services）区分。第二句'有意不提供 get 工具'虽提供背景，但主要传达的是没有单独获取工具的意图，对用途本身帮助有限。

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?

描述没有说明何时使用此工具或与其他工具的替代关系。仅提到没有 get 工具，暗示此列表是唯一获取方式，但未明确给出使用场景、前提条件或排除条件，缺乏实际指导。

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, covering the safety profile. The description adds behavioral details beyond annotations: the list is sorted by priority descending and does not include schema. This provides useful context without contradicting 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, front-loaded sentences with no wasted words. It directly states the core function and the key exception (no schema) in the first sentence, and the usage pointer in the second.

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 is adequate for a simple listing tool: it specifies the output (plugin names), ordering, and what is excluded, and references the schema tool. It doesn't mention response format or pagination, but the tool is simple enough and annotations are rich. A slight gap is that it doesn't mention the optional subsystem filter, but the schema covers that.

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

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

Schema description coverage is 100% for the single optional parameter, so the schema fully documents the subsystem parameter. The tool description adds no additional parameter semantics, but it doesn't need to since the schema is comprehensive. Baseline 3 is appropriate.

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

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

The description clearly states the tool queries a list of plugin names, sorted by priority descending and excluding schema. It also distinguishes itself from the sibling tool apisix_get_plugin_schema by noting that schema should be retrieved separately.

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

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

The description explicitly says '需要字段定义时另调 apisix_get_plugin_schema', providing a direct alternative when schema definitions are needed. This clearly guides when to use this tool versus the schema 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 indicate read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context: in v2 format, filter parameters are silently ignored, and the return result will explicitly indicate this. It also notes that service_id/upstream_id filtering requires APISIX ≥3.13, which is non-obvious and beyond what annotations or the schema convey.

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 well-structured: a one-line core purpose, followed by filtering capabilities and a critical version caveat. Every sentence adds value with no fluff or redundancy, and essential 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?

For a list tool with 9 optional parameters and no output schema, the description covers the primary purpose, filtering options, version constraints, and a key edge case about v2 behavior. It does not describe the return format, but pagination and projection parameters are documented in the schema, and the read-only nature is clear from annotations and description.

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% description coverage across all 9 parameters, so the schema already documents each parameter clearly. The description synthesizes the filter parameters into logical groups (v3 native vs reference filtering) and adds the v2 caveat, but this does not significantly extend the per-parameter meaning.

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

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

The description opens with '查询路由列表' (query route list), clearly identifying the action (list) and resource (routes). It goes beyond a generic statement by enumerating supported filter criteria and version-specific behavior, which distinguishes it from sibling tools like apisix_get_route that retrieve a single route.

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 stating the tool lists routes and supports various filters, but it does not explicitly compare with alternatives or state when to prefer this over apisix_get_route. It does provide a version constraint for reference filtering, which offers some guidance, but no explicit 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?

The description discloses no behavioral traits beyond what annotations already provide. Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint=false. The description only repeats that it is a query operation, adding no context about pagination behavior, default page size, or response format. Since the description contributes nothing beyond annotations, transparency is low.

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

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

The description is a single short sentence with no unnecessary words. It is appropriately sized for the minimal information it conveys, though it could be more informative. There is no wasted content, structure, or redundancy.

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

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

Given the tool has 4 parameters, pagination, field selection, and no output schema, the one-sentence description is insufficient. It does not explain what the response contains, how pagination works, or how to use the detail/fields parameters effectively. The schema helps but the description should provide at least a minimal overview of behavior.

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 with descriptive parameter fields (page, detail, fields, page_size), each with clear Chinese descriptions. The tool description does not add any parameter-level meaning, but the schema fully carries that burden. Baseline 3 is appropriate.

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

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

The description '查询服务列表' clearly states the action (query) and resource (service list), which aligns with the tool name. However, it does not add any scope or differentiation from sibling list tools like apisix_list_routes or apisix_list_upstreams, so it stops 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. There is no mention of prerequisites, filters, or scenarios where apisix_get_service would be more appropriate. The description is a bare statement of what it does, not when to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds the behavioral nuance that no get tool exists, which is useful context about how to retrieve stream route details. It does not describe pagination or response format, but annotations cover the safety aspects.

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

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

The description is a single sentence with two clauses, each providing distinct value: the primary purpose and a key usage caveat. No filler words or redundant information.

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

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

Given the tool's moderate complexity (4 params, all documented, no output schema), the description provides the crucial missing context that no get tool exists. This makes the tool self-explanatory for a list operation, though it could mention response format or pagination defaults if those were non-obvious.

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 four parameters have descriptions in the schema (100% coverage), so the schema carries the parameter semantics. The description adds no extra parameter guidance, leaving the baseline 3 appropriate.

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

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

The description states '查询流路由列表' (query stream route list), a specific verb and resource. It also distinguishes from siblings by mentioning the intentional absence of a get tool, clarifying this is the list operation for stream routes.

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 phrase '有意不提供 get 工具' communicates that there is no get-tool alternative for stream routes, implying this list tool is the primary way to access them. This gives clear context but doesn't explicitly exclude cases where sibling list tools 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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds no behavioral context beyond the basic query operation. It does not contradict the annotations, but it also does not disclose any additional traits such as pagination behavior or projection semantics.

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

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

The description is a single short sentence, which is concise. However, it merely restates the title and adds no substantive information, so it doesn't fully earn its place. It is not overlong, but it could be more informative while staying concise.

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 tool with 4 optional parameters and no output schema, the description is incomplete. It doesn't mention pagination, return format, or any behaviors beyond 'query list'. The schema covers parameters, but since there is no output schema, the description should provide some indication of the response structure. This is a clear gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description itself provides no parameter-specific information, but the schema fully documents page, detail, fields, and page_size with default values and constraints.

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 specifies the action (query) and resource (upstream list). It distinguishes the tool from get_upstream by indicating list semantics and from other resource-specific list tools by naming the resource. However, it is effectively a restatement of the tool name and title, lacking additional qualifiers or scope details that would fully differentiate it from sibling list 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 provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or comparisons to sibling tools. The sibling tool names appear only in the context signals, not in the description itself.

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

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

注释已声明 readOnlyHint/openWorldHint/idempotentHint/destructiveHint，描述额外提供了版本要求（≥3.5）、校验范围限制（不校验引用存在性与插件配置合法性）、通过不代表写入成功，以及 <3.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?

描述仅 3 句话，首句即点明核心功能，第二、三句提供必要限制和版本行为，无冗余或重复信息，结构紧凑且重点前置。

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?

工具简单且参数完备，注释丰富。描述涵盖了版本要求、校验范围和降级行为，但未说明具体返回值（如成功/失败如何表示）及降级时的确切表现，略有欠缺，但整体足以指导使用。

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 中两个参数（resource、config）均有详细描述，覆盖率达 100%。描述虽提到'资源配置'，但未在 schema 基础上增加额外参数级语义，因此按基线给予 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?

明确说明工具用于校验资源配置是否符合 JSON schema，动词（校验）+ 对象（资源配置）+ 标准（JSON schema）清晰。与兄弟工具的 get/list 操作区分明显，具有唯一性。

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?

描述隐含使用场景（提交资源配置前进行预校验），并通过'仅校验 JSON schema，不校验引用存在性与插件配置合法性'和'通过不代表写入必定成功'提示了边界。虽然未显式说明何时使用 vs 替代工具，但兄弟工具均无校验功能，上下文足够清晰。

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