Server Quality Checklist

Tool Scores

• statusA
  4/5.0
  Behavior4/5

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

  With no annotations, the description carries the full disclosure burden. '只读' explicitly communicates that the tool has no side effects, and the list of status areas clarifies its scope. It does not discuss permissions or output details, but the read-only signal is the key behavioral trait for this type of tool.

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

  Conciseness5/5

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

  The description is two short sentences that deliver the operation, scope, read-only guarantee, and usage order without any filler. The core action is front-loaded and every clause adds value.

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

  Completeness4/5

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

  For a simple read-only status tool with zero required parameters and no output schema, the description covers the tool's role and provides an ordering cue for use. It could mention the output format, but the enumerated status areas and the 'read first' instruction make it adequately complete.

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

  Parameters3/5

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

  Schema description coverage is 100%, so both parameters are already self-documented. The description adds no parameter-specific meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

  Purpose4/5

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

  The description uses the verb '查看' (view) and clearly enumerates the status resources: current project, board type, flashing budget, serial port occupation, and download mode status. It is clear and specific, but it does not explicitly differentiate from sibling tools such as read_serial.

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

  Usage Guidelines4/5

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

  The phrase '调用前先看这个' explicitly directs the agent to check this tool before making other calls, which is actionable usage guidance. It also flags the tool as read-only, but it does not name alternatives or state exclusions.

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

• compileA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden. It discloses meaningful behavioral traits: no hardware interaction, read-only semantics, free invocation, and no call limits. It could add more detail about build artifacts or failure behavior, but the core safety-relevant behavior is well covered.

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

  Conciseness5/5

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

  A single compact sentence conveys the action, the return value, the safety profile, and usage freedom. There is no redundant content, and the core facts are front-loaded.

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

  Completeness4/5

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

  For a simple, optional-parameter compile operation, the description plus schema is largely sufficient. It communicates the output concept ('firmware occupancy') even without an output schema. Minor missing details like output format or compile duration prevent a perfect score.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already documents both parameters clearly. The description adds no parameter-level meaning beyond what the schema provides, which matches the baseline expectation.

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

  Purpose5/5

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

  The description states a specific verb ('compiles') and resource ('project'), plus the distinct return value ('firmware occupancy'). It also signals that the tool does not touch hardware, which clearly separates it from sibling tools like flash and erase_flash.

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

  Usage Guidelines4/5

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

  The description gives clear usage context: it is safe, read-only, free to call, and has no rate limits, so an agent knows when it is appropriate to invoke. It does not explicitly name alternatives for hardware-affecting operations, but the safety framing makes the boundary clear.

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

• flashA
  4.2/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full burden and delivers: '⚠️ 有副作用' discloses that the tool mutates state, and '受烧录预算上限保护' reveals a budget-cap safeguard. The status-check precondition implies the call can fail due to quota/port contention. It does not mention that existing firmware gets overwritten or how exhaustion errors surface, but the core behavioral traits are disclosed.

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

  Conciseness5/5

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

  Three short sentences with zero waste: purpose first, then side-effect warning, then the precondition. Each sentence earns its place and the structure is front-loaded with the core action. This is exemplary conciseness.

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

  Completeness4/5

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

  For a mutating tool with no annotations and no output schema, the description covers the critical invocation context: side effects, budget protection, and the status-check prerequisite. The schema covers all four parameters, so nothing needed to invoke correctly is missing. The only gap is post-call behavior/return value, which is a minor omission given the strong schema coverage.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline is 3: every parameter (port, board, reason, project_dir) is already documented in the schema. The description adds only marginal context by tying reason to the budget concept (justifying another flash), but no essential parameter meaning is added beyond the schema.

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

  Purpose5/5

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

  The description states a specific verb and resource ('把项目烧录到开发板' — flash the project to the development board). This clearly distinguishes it from siblings: erase_flash (erasing), compile (building), read_serial (reading serial output), and status (checking state). An agent can select this tool without opening the schema.

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

  Usage Guidelines4/5

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

  The description gives an explicit, actionable precondition: '调用前先用 status 确认还有额度、串口空闲' — check status first to confirm quota and serial port availability. This names the sibling status and the condition that gates usage. It does not explicitly state when not to use flash or mention alternatives like compile/erase_flash, so it stops short of full exclusion guidance.

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

• erase_flashA
  4.4/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden and does so thoroughly: it warns the operation is dangerous and irreversible, clarifies it erases the entire flash, and reveals that execution is deferred until the server asks the user for a confirmation word. This goes beyond a basic 'erase flash' statement.

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

  Conciseness5/5

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

  The description is compact and front-loaded with the critical warning and usage condition before the behavior detail. Every sentence adds value: danger, when to use, and the confirmation-step behavior.

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

  Completeness4/5

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

  For a destructive operation with no output schema and no annotations, the description covers the essential safety context, usage trigger, and post-call confirmation requirement. It lacks only minor details such as potential side effects beyond data loss or expected output, but nothing critical is missing.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already documents all four parameters. The description itself adds no parameter-level meaning, though the schema's port note about auto-detection after flashing provides useful context. Baseline 3 is appropriate.

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

  Purpose5/5

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

  Description uses a specific verb and resource: '擦除整块 flash' (erase entire flash) and explicitly notes it is unrecoverable. This clearly distinguishes it from sibling tools such as flash, which writes firmware, and read_serial, which reads output.

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

  Usage Guidelines4/5

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

  The description states explicit conditions for use: '只在怀疑 flash 内容损坏或要彻底重置时用' (only when suspecting corruption or wanting a full reset). It does not name an alternative tool or provide a when-not-to-use, but the conditions are specific enough to guide selection.

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

• read_serialA
  4.5/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full behavioral burden. It states the tool is read-only, does not make PASS/FAIL judgments, and has a critical timing constraint for boot log capture. It also explains the exact kind of output returned, which is strong, non-redundant behavioral disclosure beyond the schema.

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

  Conciseness5/5

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

  The description is compact, front-loaded with the core function and return type, then providing essential warnings and timing instructions. Every sentence earns its place; there is no filler or repetition of schema data.

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

  Completeness5/5

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

  Given no output schema, the description sufficiently explains what the agent can expect (raw text and objective stats) and the tool's limitations (no PASS/FAIL verdicts). It also provides critical workflow context — call immediately after flash for boot logs — making this complete for an agent to invoke correctly.

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

  Parameters3/5

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

  Schema description coverage is 100%, so all four parameters are already documented with their meanings (port auto-detection, board enum, duration range with default, project_dir default). The description does not add extra parameter-specific detail beyond the schema, so the baseline 3 is appropriate.

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

  Purpose5/5

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

  The description states a clear, specific action — read serial output — and describes the return content (raw text plus objective statistics: empty, crash keyword hits, reset count). It is clearly distinguishable from sibling tools like flash, erase_flash, compile, and status, since it is the only one focused on reading serial data.

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

  Usage Guidelines4/5

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

  The description gives explicit context on when to use the tool: it is read-only and freely callable, and it emphasizes that boot logs must be captured immediately after a successful flash. It does not explicitly name sibling alternatives or state when not to use it, but the timing guidance and read-only note provide clear contextual usage.

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