Server Quality Checklist

Tool Scores

• list_packagesA
  4/5.0
  Behavior4/5

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

  No annotations exist, so the description carries the full burden. It adds meaningful behavioral context: group values vary by workspace, name_filter is case-insensitive, and list_groups should be called first. It doesn't explicitly state the output format or read-only nature, but 'List' implies read-only and the filtering semantics are 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.

  Conciseness4/5

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

  Two sentences with a clear front-loaded purpose. The parenthetical example is informative but slightly wordy; overall it is concise and well-structured.

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

  Completeness3/5

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

  Given the absence of output schema and annotations, the description needs to cover return values and all parameters. It provides strong filter guidance and a prerequisite, but omits workspace_root semantics and the shape of returned data, leaving notable gaps.

  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 0%, so the description must compensate. It explains group, subgroup, and name_filter clearly, but does not mention workspace_root at all, leaving one of four parameters undefined.

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

  Purpose5/5

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

  The description clearly states 'List ROS2 packages in the workspace' with a specific verb and resource. It distinguishes from siblings by focusing on packages rather than groups (list_groups) or dependencies (get_package_dependencies).

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

  Usage Guidelines4/5

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

  Explicitly instructs to 'Call list_groups first to see the actual group/subgroup values', providing a clear prerequisite and context for using filters. It does not explicitly state when not to use this tool or name alternatives, but the directional guidance is strong.

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

• get_package_dependenciesA
  4.1/5.0
  Behavior4/5

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

  With no annotations, the description carries the behavioral burden. It discloses that dependencies come from package.xml, supports filtering by dependency types, and can traverse the full closure transitively. It doesn't mention return format or potential side effects, but the read-only nature is implied by 'get'.

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

  Conciseness5/5

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

  The description is two sentences, with the main purpose front-loaded and parameter details following. Every sentence adds value with no filler.

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

  Completeness3/5

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

  While the core functionality is covered, the tool has four parameters and no output schema. The description omits workspace_root, and the return format is not addressed. This leaves the agent with some uncertainty about how to invoke the tool fully and interpret results.

  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 0%, so the description must compensate. It explains depend_types and transitive in detail, and package_name is obvious. However, workspace_root is not mentioned at all, leaving a parameter unexplained. This is a notable gap for a 3-param tool.

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

  Purpose5/5

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

  The description clearly states that the tool retrieves package dependencies and reverse dependents, using a specific verb and resource. It distinguishes from sibling tools like list_packages, which likely only lists packages without dependency relationships.

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

  Usage Guidelines4/5

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

  The description provides clear context on what the tool does and how to control its behavior via depend_types and transitive. It doesn't explicitly mention when not to use it or alternative tools, but the context is sufficient for an agent to decide when this tool is relevant.

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

• list_groupsA
  4.1/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. It discloses the derivation logic (from src/ directory layout, configurable via .rosgraph-mcp.toml) and notes the config option. Missing details like return format or side effects, but for a read-only list operation this is acceptable.

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

  Conciseness5/5

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

  Three sentences, each earning its place: first states purpose, second explains derivation/default behavior, third provides usage guidance. No redundancy or filler.

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

  Completeness4/5

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

  Given no output schema and no annotations, the description covers the important aspects: what groups are, how they are derived, optional configuration, and when to use it. It does not describe return format, but for a list tool the purpose is clear enough.

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

  Parameters2/5

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

  Schema description coverage is 0%, and the description never explicitly explains the workspace_root parameter. It mentions 'this workspace' but does not connect it to the parameter, leaving the agent to infer that workspace_root specifies the workspace. The description adds little beyond the schema's property name and type.

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

  Purpose5/5

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

  The description uses a specific verb ('List') and clearly names the resource ('groups and subgroups') and scope ('in this workspace'). It distinguishes itself from sibling tools like list_packages by focusing on group/subgroup structure.

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

  Usage Guidelines4/5

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

  It gives explicit usage timing: 'Call this before using subgroup filters on list_packages/dashboard'. However, it does not mention when not to use it or explicitly compare against alternatives, so it lacks exclusion criteria.

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

• rescan_workspaceA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries full burden. It discloses the core behavior (re-scanning package.xml files, rebuilding the cache) and the performance rationale. It implies overwriting via 'rebuild' but does not detail failure modes or permissions. Still, the main side effect is clearly stated.

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

  Conciseness5/5

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

  Two sentences with no waste: first states action and scope, second gives the usage trigger and rationale. Information is front-loaded and every sentence earns its place.

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

  Completeness3/5

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

  The description covers the purpose and trigger, but omits details about the optional `workspace_root` parameter and any return value or success/failure indication (no output schema exists). For a simple action, this is a noticeable gap.

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

  Parameters2/5

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

  The only parameter, `workspace_root`, has no description in the schema and is not mentioned in the tool description at all. With 0% schema coverage, the description should compensate but does not; the agent must infer meaning from the parameter name alone.

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

  Purpose5/5

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

  The description uses a specific verb ('Rebuild') and resource ('package index cache'), and explicitly scopes to 'all package.xml files' under a workspace. This clearly distinguishes it from the sibling listing/query tools (list_packages, etc.).

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

  Usage Guidelines5/5

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

  The description gives explicit when-to-use guidance: 'Call this after pulling new source or after `vcs import` changes the set of packages'. It also explains why (index is not auto-refreshed for performance), implying when it is not needed.

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