Server Quality Checklist

Tool Scores

• nexus_list_operationsA
  3.5/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. The description only explains the tool's purpose and when to use it, but does not mention what the tool returns (e.g., a list of operation IDs, summaries, pagination) or any other side effects. This lack of behavioral detail is a significant gap for a tool invoked before taking actions.

  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, front-loaded with the core function and then the usage guidance. Every word earns its place, with no redundant information. This is an ideal example of conciseness.

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

  Completeness2/5

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

  The tool has four parameters, no output schema, and no annotations, so the description must cover both behavior and return values. It only covers the purpose and usage, leaving the agent uncertain about what the tool actually returns (e.g., list structure, fields per operation). This is incomplete for a tool meant to guide subsequent actions.

  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 75% (three of four parameters have descriptions), but the 'limit' parameter has no description. The tool description itself adds no additional meaning beyond the schema, and it does not explain how 'search', 'method', or 'service' interact or affect results. Since the schema is not fully complete and the description does not compensate, the score is low.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Find documented Nexus Dashboard Infrastructure or Manage API operations.' It uses a specific verb ('Find') and resource ('operations'), and the phrase 'Use this before an unfamiliar read or change' signals that this is a discovery tool, differentiating it from sibling tools like nexus_read or nexus_describe_operation.

  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 usage context: 'Use this before an unfamiliar read or change.' This tells the agent when to invoke the tool, but it does not explicitly mention when not to use it or name alternative tools. Since it provides a clear directive without exclusions, it earns a 4.

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

• nexus_readA
  3.7/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden. It clearly discloses the critical safety trait (read-only, never changes configuration), which is valuable. However, it omits other behavioral details such as how errors are reported, response structure, or any dependencies on operation documentation.

  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, both front-loaded with the core purpose and safety guarantee. Every word earns its place, making it highly concise and easily scannable.

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

  Completeness2/5

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

  The tool is a generic wrapper with three parameters and no output schema, so the description needs to set expectations. It covers read-only safety but offers no guidance on how to determine valid operation IDs or how to populate path/query parameters. It also does not reference sibling tools like nexus_list_operations or nexus_describe_operation for further context, leaving significant gaps.

  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 description itself adds no parameter information. The schema covers operation_id only (33% coverage), pointing to nexus_list_operations, but path_parameters and query_parameters are generic objects with no explanations. Given the low schema coverage, the description should have compensated but did not.

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

  Purpose5/5

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

  The description clearly states the tool calls a 'documented read-only (GET) Nexus Dashboard API operation' and emphasizes it 'never changes configuration,' which distinguishes it from the sibling change tools. The verb and resource are specific and unambiguous.

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

  Usage Guidelines4/5

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

  The read-only and 'never changes configuration' statements explicitly signal that this tool is for retrieval, not modifications. The operation_id schema description further guides the agent to get the ID from nexus_list_operations, providing useful context. However, it does not explicitly name alternative tools for when to use them.

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

• nexus_describe_operationA
  3.8/5.0
  Behavior3/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 accurately states what the tool returns but does not add extra behavioral context such as whether the operation is read-only, whether it executes anything, or any error conditions. For a 'describe' tool, side effects are unlikely, but the description does not explicitly disclose that it only retrieves schema and does not invoke the operation.

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

  Conciseness5/5

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

  The description is a single, clear sentence that is front-loaded with the main verb and delivered in a straightforward structure. There is no redundant or extraneous wording; every word earns its place.

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

  Completeness4/5

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

  Given the tool's simplicity (one parameter, no output schema), the description fully conveys what the tool returns and is sufficiently complete on its own. The only minor gap is that it doesn't explicitly state that the operation is not executed, but this is easily inferred from the verb 'Show' and the tool name.

  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%: the operation_id parameter has a descriptive explanation (including how to format it and disambiguate). The tool description itself adds no additional parameter meaning, so it contributes no value beyond what the schema already provides. This matches the baseline for high schema coverage.

  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 the specific verb 'Show' and clearly states the resource: 'exact documented path parameters, query parameters, and JSON request body schema for a Nexus Dashboard operation.' This goes beyond the tool name and distinguishes it from siblings like nexus_apply_change or nexus_list_operations, which perform different functions.

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

  Usage Guidelines3/5

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

  The intended use case is implied: you'd call this to see an operation's schema before invoking it. However, the description does not explicitly say when to use it versus alternatives, nor does it mention prerequisites like listing operations first. The parameter description references nexus_list_operations, but that is in the schema, not the main description.

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

• nexus_apply_changeA
  4/5.0
  Behavior3/5

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

  With no annotations, the description discloses some behavioral traits: it requires a user-controlled approval code and has an additional server-side gate for disruptive actions. However, it does not explain what happens after applying, reversibility, or error conditions, leaving gaps in transparency.

  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, purpose first, with no redundant wording. Every sentence contributes unique value: function, prerequisite, and safety gate.

  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 two-parameter write tool with no output schema, the description covers the critical context: it is the apply step, needs server-side enablement, an approval code, and an extra gate for disruptive actions. It omits details like return values and exact failure modes, but is sufficiently complete for basic usage.

  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 description adds no extra meaning beyond what the schema already provides for change_id and approval_code. It mentions the approval code but repeats rather than extends 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 uses a specific verb 'Apply' with a clear resource ('previously previewed change'), immediately distinguishing it from siblings like nexus_read and nexus_prepare_change. It conveys that this is the execution step in a prepare/apply workflow.

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

  Usage Guidelines4/5

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

  It clearly states prerequisites ('previously previewed change') and actionable requirements (server-side write enablement, approval code, additional gate for disruptive actions), implying it should follow nexus_prepare_change. However, it does not explicitly name alternatives or state when not to use the tool.

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

• nexus_prepare_changeA
  4/5.0
  Behavior4/5

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

  Since no annotations are provided, the description carries the full burden of disclosing behavior. It clearly states that the change is not sent, and that the returned change_id is one-time, which is critical lifecycle information. It doesn't disclose error handling or side effects, but the core 'preview without sending' trait 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?

  The description is a single, information-dense sentence covering the action, scope, safety property, and output. It is front-loaded with the verb 'Validate' and contains no waste.

  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?

  With no output schema, the description should clarify what the 'preview' consists of and the exact return format beyond a change_id. It also leaves out error handling and prerequisites (like needing to call nexus_describe_operation first). The essential workflow is conveyed, but dependencies and edge cases are only implied.

  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 coverage is 67%, and the description adds no parameter semantics. Path and query parameters remain undocumented in both schema and description, and the description doesn't reinforce the relationship between the body and nexus_describe_operation's request_body schema. The tool description leaves users without guidance on how to populate these params.

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

  Purpose5/5

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

  The description clearly states the specific action ('Validate and preview'), the resource ('a non-GET Nexus Dashboard API change'), and the key output ('one-time change_id'). It effectively distinguishes from siblings like nexus_apply_change (which presumably sends the change) and nexus_read (which handles GET operations).

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

  Usage Guidelines4/5

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

  The description implies that this tool is a required prerequisite for applying a change ('required to apply exactly this request'), and the 'non-GET' qualification tells users this is not for read operations. However, it doesn't explicitly name alternatives or state when not to use this tool beyond the non-GET filter.

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

• nexus_troubleshoot_switchA
  4.1/5.0
  Behavior4/5

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

  With no annotations provided, the description carries full behavioral disclosure burden. It explicitly states 'This is read-only,' which is a critical safety trait. It also lists the data categories collected, giving a clear picture of the operation's scope, though it does not mention potential performance impact or output format.

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

  Conciseness5/5

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

  Two concise sentences. The action and scope are front-loaded, the list of contents is compact, and the read-only note is a single clause. There is zero wasted language.

  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 two-parameter read-only tool, the description is largely complete: it explains the operation, lists what is collected, and states safety. The lack of explicit return format or parameter details prevents a perfect score, but the listed bundle contents provide adequate context for a troubleshooting tool.

  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 coverage is 0% (no parameter descriptions), and the description does not explicitly explain what 'fabric_name' or 'switch_id' mean. It implies 'switch_id' identifies the switch through 'for one switch,' but 'fabric_name' is never connected to the bundle. The description adds little meaning 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 uses a specific verb ('Collect') and resource ('troubleshooting bundle for one switch'), and explicitly lists what the bundle contains. This clearly distinguishes it from sibling tools like nexus_read (generic read) or nexus_apply_change (mutation).

  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 'focused troubleshooting bundle' clearly implies when to use this tool (during troubleshooting). It does not explicitly name alternatives or exclusions, but the context makes the use case obvious relative to the change-management siblings.

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