Server Quality Checklist

Tool Scores

• get_operatorA
  3.5/5.0
  Behavior2/5

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

  No annotations are provided, so the description must carry full behavioral transparency burden. It only states the action 'look up' and does not disclose whether this is a read-only operation, what happens if the operator is not found, or any other behavioral traits. This is a minimal disclosure that leaves the agent uncertain about important side effects or error conditions.

  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 sentence, front-loaded with the action and resource. It is concise and free of filler or redundant information, earning a perfect score for conciseness and structure.

  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 tool is simple (one parameter) and has an output schema, but the description lacks critical contextual details such as the read-only nature and error behavior. While the output schema may cover return values, the absence of annotations and minimal description leaves the agent without complete context on how this tool behaves in different scenarios.

  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?

  The input schema provides 100% coverage of the single parameter user_name, with a clear description. The tool description adds no additional meaning beyond the schema, but with full schema coverage the description is not required to supplement parameters. Baseline of 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 is specific and unambiguous: 'Look up a BigFix operator (console user) by name.' It uses a clear verb ('look up'), identifies the resource ('BigFix operator'), and specifies the method (by name). It distinguishes itself from sibling tools like whoami (current operator) and get_server_info (server information).

  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 description implies when to use the tool: when you need to look up an operator by name. However, it does not explicitly state when to use it versus alternatives, nor does it mention any exclusions or prerequisites. The usage context is inferred rather than fully articulated.

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

• get_dashboard_variableA
  3.6/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden for behavioral disclosure. It states 'read-only', which is a useful safety signal, but it does not mention potential errors, permissions, or any side effects. The transparency is adequate but minimal.

  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, front-loaded sentence that conveys the core purpose without wasted words. It is succinct and easy to parse.

  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 getter with an output schema present and full schema parameter coverage, the description is mostly complete. It tells the agent what the tool does and that it's read-only. It lacks broader usage context, but the simplicity of the tool keeps this from being a significant gap.

  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. The description adds no additional meaning beyond the schema's own parameter descriptions, which fully document 'dashboard_name' and 'var_name'.

  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 ('Read') and identifies the exact resource ('BigFix dashboard datastore variable value'), clearly distinguishing it from sibling tools that target other resources. The parenthetical '(read-only)' reinforces the operation type.

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

  Usage Guidelines2/5

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

  No guidance is provided on when to use this tool versus alternatives. The sibling list includes many other read-oriented tools, but the description offers no exclusions, prerequisites, or explicit context for selection.

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

• list_sitesA
  3.6/5.0
  Behavior2/5

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

  No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only states the visibility scope, but does not mention return format, pagination, or any side effects. The verb 'list' implies read-only, but this is not explicitly confirmed.

  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, front-loaded sentence with no redundant phrasing. Every word earns its place, making it highly concise and well-structured.

  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 parameterless list tool with an output schema, the description is nearly complete. It clearly states what the tool does and the scope, though it could benefit from a note about potential limitations (e.g., whether the list is always exhaustive or if operator visibility is the only filter).

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

  Parameters4/5

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

  The tool has zero parameters, so the description is not required to add parameter-level meaning. Per the rubric, a tool with no parameters receives a baseline score of 4.

  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 resource ('sites') with an explicit scope ('visible to the configured operator'), clearly stating the tool's function. It also differentiates this tool from siblings like 'whoami' or 'get_computer_group' by focusing on sites.

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

  Usage Guidelines2/5

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

  There is no guidance on when to use this tool versus alternatives such as 'get_computer_group' or 'api_get'. The description implies a simple listing operation but provides no context, prerequisites, or exclusions to help an agent choose it over other tools.

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

• get_server_infoA
  3.8/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 accurately describes a read-only 'Get' operation from a specific endpoint, but omits any details about authentication requirements, response format, or potential side effects. For a simple no-parameter tool, this is adequate but not rich.

  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, front-loaded sentence that states the verb, resource, and endpoint with no wasted words. It is appropriately concise for the tool's simplicity.

  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 (0 params, no annotations, output schema present), the description is largely complete: it states what it does and where. However, it lacks any context about prerequisites or read-only nature, so it falls just short of a perfect score.

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

  Parameters4/5

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

  The tool has zero parameters, so the schema is trivially covered. The description doesn't need to explain parameters, and the baseline for 0 parameters is 4. No additional semantic information is required.

  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 action ('Get') and the resource ('BigFix root server info (version, etc)') along with the exact endpoint ('from /api/serverinfo'). This distinguishes it from sibling tools like whoami or api_get, which serve different purposes.

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

  Usage Guidelines2/5

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

  No explicit guidance is provided on when to use this tool versus alternatives such as api_get. The endpoint implies the use case (retrieving server info), but there are no exclusions or alternative recommendations, leaving the agent to infer usage from the endpoint and sibling names.

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

• client_query_submitA
  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 full transparency burden. It discloses the non-obvious targeting constraint and that target_all is scoped by the operator's permissions, not the whole BigFix deployment. This is meaningful, though it does not discuss submission latency or polling behavior.

  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 dense sentences with high information density. Every phrase contributes, and the most essential usage rule (set exactly one target) is 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 5-parameter submission tool with no annotations, the description covers the main input constraints and a critical semantic caveat. An output schema exists, so return values need not be described. The only notable gap is the lack of a pointer to sibling tools for alternative query workflows.

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

  Parameters4/5

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

  Schema coverage is 100%, so the baseline is 3, but the description adds crucial extra semantics: mutual exclusivity of targeting parameters, target_relevance as an applicability expression, and the real meaning of target_all. These clarifications go beyond the schema property descriptions.

  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 clearly states the action ('Submit a BigFix client (fast) query') and resource, and adds useful targeting detail. It distinguishes from session relevance by specifying 'client', but does not explicitly contrast with the sibling 'client_query' tool.

  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 concrete invocation guidance: 'set exactly one of target_all, target_computer_ids, target_computer_names, or target_relevance' and clarifies the operator-scope limitation of target_all. It does not mention when to prefer this tool over siblings, so it misses the exclusion side.

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

• api_getA
  4.3/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 of disclosing behavior. It explicitly states that GET is non-mutating and that response text is truncated to 50KB, which are critical safety and limitation details. It could mention error behavior or authentication, but the core behavioral traits are 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 succinct, with the main purpose front-loaded in the first sentence and three short, information-dense sentences total. Every sentence earns its place, covering purpose, safety, discovery, and a key limitation.

  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 the tool's simplicity (one parameter, fully documented schema, and an output schema available), the description is complete for an agent to select and invoke it correctly. It explains scope, non-mutation, truncation, and how to discover endpoints, covering all necessary aspects without redundancy.

  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?

  The input schema already provides 100% coverage of the 'path' parameter, including examples and the allowance for query strings. The description adds the specific 'help' endpoint example, but this is also present in the schema, so it adds minimal value beyond the structured data.

  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 is a read-only escape hatch for GET requests to any BigFix REST API path under /api/, with a specific verb and resource. It distinguishes itself from sibling tools by being a generic low-level access point rather than a purpose-built endpoint.

  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 for when to use the tool: anytime a read-only GET request to the BigFix REST API is needed. It also gives a practical tip to use path 'help' for discovery. However, it does not explicitly name alternatives or state when not to use it, which would warrant a 5.

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

• client_query_resultsA
  4.3/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 of behavioral disclosure. It explains key traits: results are cumulative, no completion flag, and repeated calls are safe/cheap. This goes beyond the schema and provides important operational context.

  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 no wasted words. The first sentence states the purpose directly, and the second adds essential behavioral nuance. Front-loaded and efficient.

  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?

  For a simple one-parameter tool with an output schema, the description covers purpose, usage (polling approach), and key behavioral traits. It is sufficiently complete for an agent to decide when and how to use the tool. The output schema covers return value details, so no further explanation is needed.

  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?

  The input schema already documents query_id as 'Query ID returned by client_query_submit' with 100% coverage. The description reinforces the 'previously submitted' link but adds little beyond that. Baseline 3 is appropriate since the schema does the heavy lifting.

  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 ('Fetch') and a specific resource ('current results for a previously submitted client fast query'), distinguishing it clearly from sibling tools like client_query_submit and client_query. The phrase 'previously submitted' clarifies the stateful nature of this tool.

  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 polling guidance: results are cumulative, there is no completion flag, and it is safe/cheap to call repeatedly until reported_count stabilizes. It does not explicitly name alternatives or exclusions, but the context makes it obvious that this is the retrieval counterpart to client_query_submit.

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

• get_computer_groupA
  4.3/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 behavioral transparency burden. It conveys that the operation is a read-only lookup and discloses that it intentionally bypasses mutable connection state, which is valuable behavior context. It does not discuss potential errors or authentication, but for a simple lookup with an output schema, this is adequate.

  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 concise and well-structured: the first sentence states the primary purpose, and the second sentence explains the implementation rationale. No information is redundant or excessive.

  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?

  The tool has only two required parameters, full schema coverage, and an output schema. The description provides the necessary context about what the tool does and why it is built a certain way. For a straightforward lookup tool, this fully covers the agent's needs.

  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?

  The input schema already documents both parameters (site_path and group_name) with examples, giving 100% schema description coverage. The tool description adds little beyond reinforcing the 'explicit site path' aspect, which is a minor enhancement. Therefore, 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.

  Purpose5/5

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

  The description states a specific action ('Look up'), a clear resource ('computer group'), and the precise scope ('by name within an explicit site path'). It also distinguishes itself from an alternative implementation (besapi's get_computergroup), making the tool's purpose unambiguous even among sibling tools.

  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 clarifies that this tool is the preferred choice when an explicit site path is required and the mutable state of besapi's get_computergroup should be avoided. While it doesn't explicitly mention sibling tools or provide exclusion criteria, it gives a clear rationale for choosing this tool over the alternative implementation.

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

• client_queryA
  4.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 behavioral disclosure burden. It discloses that the tool polls, waits until done or timeout, and constraints targeting to exactly one mode. It also clarifies that target_all means within the operator's scope. It does not explicitly state side-effect freedom (e.g., read-only), but the query nature makes that implicit.

  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: two sentences, first being the core action, second addressing targeting constraints. Every clause provides necessary information without fluff. The most important usage guidance is 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?

  Given 9 parameters, no annotations, and an output schema (which covers returns), the description covers the essential behavioral context: synchronous polling, timeout, targeting options, and scope limits. It omits details about poll_interval and timeout ranges, but those are in the schema. It is sufficient for a tool of this complexity.

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

  Parameters4/5

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

  Schema coverage is 100%, but the description adds meaning beyond the schema: target_relevance is explained as 'client relevance evaluated on each agent to decide applicability,' expected_count's default behavior is clarified ('Defaults to the targeted computer count when knowable'), and stable_polls' stopping condition is rephrased. This adds genuine value over the raw property descriptions.

  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 opens with a specific verb+resource+behavior: 'Submit a BigFix client (fast) query and wait for results, polling until done or timeout.' This clearly distinguishes it from siblings like client_query_submit and client_query_results, which handle submission and retrieval separately. The sync-and-poll nature is explicit.

  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 a clear, actionable targeting rule: 'set exactly one of target_all, target_computer_ids, target_computer_names, or target_relevance.' It also explains the operator-scope limitation. It doesn't mention alternatives like client_query_submit/results for async use, so it misses the 'when-not' guidance, but the provided context is strong.

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

• whoamiA
  4.5/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 disclosure burden. It adds valuable context about the 'is_main_operator' field and its implications for scoped vs. full-state results, and calls the tool 'cheap.' It does not explicitly mention side effects or auth requirements, but these are minimal for a read-only smoke test.

  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 no wasted words. The primary purpose is front-loaded, and the second sentence adds crucial interpretive context. Every sentence earns its place.

  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?

  The tool is simple, has an output schema (so return values need not be described), and no parameters. The description explains the key semantic nuance of is_main_operator and the tool's role as a smoke test, making it complete for selection and invocation.

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

  Parameters4/5

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

  The tool has zero parameters, so the baseline is 4. The description appropriately does not discuss parameters since there are none, and the input schema is empty with 100% coverage, so there is nothing to add.

  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 what the tool does with a specific verb and resource: 'Show the configured connection: user, root server, main operator status.' It also distinguishes itself from siblings like get_operator or get_server_info by focusing on the current connection and its role as a smoke test.

  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 says 'Cheap connectivity and permission smoke test,' which gives clear context for when to use it. It also explains how is_main_operator affects interpretation of other tool results, implying this should be used to establish context. However, it does not explicitly name alternatives or exclusions.

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

• session_relevance_queryA
  4.7/5.0
  Behavior5/5

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

  With no annotations, the description carries the full burden and does so thoroughly: it discloses the absence of a server-side result limit, warns to bound large result sets, specifies the return envelope shape, and reveals that results are scoped to the operator's visibility, potentially being a lower bound unless whoami shows is_main_operator. This is rich, actionable behavioral context.

  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 appropriately sized and well-structured: it starts with a one-sentence purpose, then a paragraph explaining the query context, then critical caveats, and finally the operator-scope note. Each sentence contributes necessary information, with no fluff. The use of examples and the raw envelope format makes it efficient.

  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 the tool's complexity, the description is remarkably complete. It covers what the tool does, the data source, return format, result limits, and scope/visibility nuances. Although an output schema exists, the description still explains the envelope structure and operator-bound implications, leaving little room for misinterpretation.

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

  Parameters4/5

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

  The schema already describes the sole parameter as 'A BigFix session relevance expression to evaluate,' and coverage is 100%, so the baseline is 3. The description adds value by providing concrete example expressions and guidance on bounding result sets (e.g., using 'firsts 100'), which helps the agent construct valid inputs and avoid performance issues.

  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 opens with a specific verb+resource: 'Evaluate a BigFix session relevance query on the root server.' It clearly distinguishes from sibling client query tools by noting 'no client round-trip' and listing the data domains (computers, fixlets, actions, sites, operators). This makes the tool's purpose 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 description explains that session relevance queries the server's already-held data with no client round-trip, which effectively tells the agent when to use this tool versus client query tools. It also provides examples and a critical caveat about no server-side result limit, implying the need to bound queries. However, it does not explicitly name alternative tools or state 'use client query for client-side data,' so there's no direct exclusion.

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