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 well: it declares the operation is offline and instant, guarantees the expression is never evaluated, and discloses the advisory nature of the inspector snapshot plus the fact that a clean report does not guarantee server acceptance. These are non-obvious behavioral caveats an agent needs.

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?

Front-loaded with the core purpose, then behavior, then usage routing, then caveats. The bullet-style clauses (parse checks, type inference, dialect classification, unbound 'it', complexity scoring) are dense but each earns its place by telling the agent what the report contains.

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?

An output schema exists, so return values need no explanation, and the description still covers the operational profile and limitations an agent must know to interpret results correctly. Nothing needed to call or correctly trust the tool is missing.

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 all four parameters are already documented, and the description does not add syntax or format detail beyond them. It reinforces concepts like dialect classification and inspector lookups, but that information is already present in the schema, so the baseline 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?

States a specific verb and resource ('Statically analyze a relevance expression') and immediately scopes it with 'WITHOUT evaluating it anywhere', which is the exact distinction that separates it from session_relevance_query and client_query. An agent can identify the tool's role 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.

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

Explicitly names when to use it ('to validate a query before session_relevance_query or client_query, or to understand a relevance error after one'), naming the exact sibling tools and the pre/post conditions. Nothing is left to inference.

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?

With no annotations, the description carries the safety profile itself and does so clearly by stating GET is non-mutating across the BigFix REST API. It also discloses response truncation via max_chars and total_chars, though it omits auth, rate-limit, and error 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 short, front-loaded with the core purpose, and every sentence adds operational value. There is no redundant restatement of the tool name or schema.

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 generic REST escape hatch with an output schema, it covers purpose, safety, discovery, and truncation adequately. It is slightly thin on endpoint-dependent auth and error semantics, but the output schema reduces the need to describe return values.

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%, so baseline is 3, but the description adds useful meaning by explaining that max_chars caps response text and total_chars reports full length. The path parameter's relative /api/ format and examples are already well covered by the schema.

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 a specific verb and resource: GET any BigFix REST API path under /api/. The phrase "read-only escape hatch" clearly frames it as a generic fallback relative to the many dedicated sibling 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?

It establishes the tool as an escape hatch and recommends path 'help' for discovering endpoints. However, it does not explicitly say when to prefer the many purpose-built sibling tools or when not to use this generic endpoint.

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?

With no annotations, the description carries the full behavioral burden, and it does convey that the result is a point-in-time, machine-scoped applicability computation. But it says nothing about read-only safety, permission requirements, result volume/pagination, or how freshness is determined, so the disclosure is only partial for a mutation-free query whose semantics matter.

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 short sentences, front-loaded with the core meaning before the clarifying framing. The API path and the second sentence slightly overlap in restating scope, but nothing is wasted or padded.

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?

An output schema exists, so return values need not be explained, and the single required parameter is schema-documented. What remains missing is routing guidance versus the many similarly-named relevance/query siblings, which keeps it from a 5.

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?

Only one parameter, and the schema already documents computer_id as the 'BigFix computer ID' at 100% coverage. The description adds no extra meaning about how to obtain that ID or what happens if it is unknown, so this sits at the baseline for schema-covered params.

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?

States a specific resource (fixlets/content applicable) scoped to one computer, and the parenthetical API path reinforces it. It also distances itself from relevance-query siblings by framing the answer as 'the patch/compliance question: what BigFix currently considers applicable to that machine.' It does not explicitly name the sibling it differs from, 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?

The phrase 'This is the patch/compliance question' implies the intended use case, which is better than nothing. However, it never tells the agent when to pick this over close siblings like session_relevance_query, qna_eval_client_relevance, or find_content, nor does it state prerequisites such as the computer needing to exist or report in.

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?

With no annotations, the description carries the behavioral burden and does well: it discloses synchronous polling behavior, termination via timeout or result-completion, and the non-obvious scope caveat that target_all means all computers the operator can see rather than all BigFix computers. It omits permission/auth requirements and any rate-limit or load implications.

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 tightly packed sentences with the action and the targeting rules front-loaded; every clause (polling, mutual exclusivity, operator scope) earns its place. Slightly dense but no 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?

An output schema exists, so return values need no explanation, and the 11 parameters are fully documented in the schema. The description covers the remaining high-value gaps (targeting exclusivity, operator-scope semantics, polling termination), leaving only the when-vs-siblings routing unaddressed.

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%, so the schema already documents each parameter and a baseline of 3 applies. The description adds meaning beyond the schema by stating the target_* parameters are mutually exclusive and that target_relevance is evaluated per-agent, steering correct selection rather than just repeating field docs.

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 names a specific verb and resource ('Submit a BigFix client (fast) query and wait for results') and clarifies the synchronous-with-polling nature of the call. It implies differentiation from async siblings (client_query_submit/client_query_results) by noting it waits, but never names those alternatives explicitly.

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 gives a concrete usage constraint for targeting ('set exactly one of target_all, target_computer_ids, target_computer_names, or target_relevance'), which is real guidance. However, it never says when to prefer this tool over the sibling polling tools (client_query_submit/client_query_results) or session_relevance_query, leaving the main selection decision to inference.

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?

With no annotations, the description carries the full burden and does well: it discloses that results are cumulative, that there is no completion flag, that repeated calls are safe and cheap, and how windowing interacts with the totals. It omits error behavior (e.g. invalid/expired query_id) and retention limits, which keeps it below 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?

Three short sentences, each earning its place: purpose, polling strategy, and pagination semantics. Front-loaded with the core action and free of 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?

An output schema exists so return shape need not be restated, and the description still covers the polling and pagination model well. What is missing for a polling tool – failure/expiry behavior on a stale query_id and any refresh cadence – is minor but leaves it slightly 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%, so the baseline is 3, but the description adds genuine meaning beyond the schema by explaining that reported_count/result_row_count reflect the full result set while rows are windowed by limit/offset – a semantic distinction the schemas do not state. That clarifying relationship lifts it above baseline.

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?

States a precise verb and resource ('Fetch current results for a previously submitted client fast query') and clearly positions itself as the read side of the submit/read pair, distinguishing it from client_query_submit. It does not contrast itself with the other query-ish sibling (client_query) or name it, so differentiation is good but not exhaustive.

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?

Gives an explicit usage pattern: call repeatedly until reported_count stops growing or the expected number of computers report, which is real when-to-use guidance. It stops short of naming alternatives or the condition under which a different tool (e.g. client_query) should be preferred.

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?

There are no annotations, so the description carries the full behavioral burden; it does add one valuable non-obvious fact — that targeting is bounded by the operator's scope, so target_all is not global. It omits the submission lifecycle entirely (whether this is asynchronous, whether results must be fetched via client_query_results, request limits), which is significant for a 'submit' tool with no 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?

Front-loaded with the action, then targeting rules, then the scope caveat — a sensible ordering with no filler. Slightly dense and repetitive ('Targeting:' followed by two sentences that both restate the same framing).

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?

An output schema exists, so return values need not be described, and the targeting model is well covered. What is missing is the operational context: how results are retrieved (the client_query_results sibling is never referenced), and whether the call is synchronous or queued, which is material for a submit-style 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%, so the baseline is 3, but the description adds meaning the schema cannot express: mutual exclusivity among the four targeting parameters, and the semantics of target_relevance as 'client relevance evaluated on each agent to decide applicability.' It does not clarify the target_all default-vs-mutual-exclusion interplay with the schema defaults.

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?

States a specific verb and resource: 'Submit a BigFix client (fast) query,' which tells an agent exactly what happens. However, it never distinguishes this from the sibling tools client_query, client_query_results, or qna_eval_client_relevance, so the agent cannot tell from the description alone which of these closely-named operations to pick.

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 gives a concrete structural rule ('set exactly one of target_all, target_computer_ids, target_computer_names, or target_relevance'), which is genuine when-to-use guidance. It does not say when to prefer this tool over client_query/session_relevance_query/xml or what the caller should do after submitting, so usage context is only implied.

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?

With no annotations, the description carries the full burden. It does disclose the returned row shape (name, id, last report time) and a non-obvious failure mode (double quotes are illegal in BigFix relevance literals), which is real added value, but says nothing about permissions, cost, or whether the search is case-insensitive at the server level.

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 short sentences, the core behavior front-loaded, then the return shape and the constraint. No filler and nothing buried.

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?

An output schema exists and the schema documents limit/offset including truncation behavior, so the description need not explain paging. For a simple 3-parameter read tool it is essentially complete, with only the lack of alternative-tool routing as a 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 coverage is 100%, so the baseline is 3, and the description adds meaning beyond the schema by explaining the double-quote restriction on name_contains and by stating the column set returned for each match. It does not expand on limit/offset, but those are already fully documented.

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?

States a specific verb and resource plus the matching rule: "Find computers whose name contains a substring." That clearly separates it from the singular get_computer/get_computer_group siblings, though no sibling is named explicitly.

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 when-to-use guidance and no routing to alternatives such as get_computer (exact lookup) or find_content. The only usage-adjacent statement is a hard constraint on the search term, which is a limitation rather than guidance about choosing this 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?

With no annotations, the description carries the burden and does well: it discloses the row shape, the null-site_path ambiguity case with the site_path_candidates fallback, and the forbidden double-quote character. It does not state read-only/safety posture, permission scoping beyond "operator can see," or rate/result-size limits (left to the schema's limit/offset and total_available).

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?

Four short sentences, front-loaded with the action and scope, then the return shape, then the edge case, then the input constraint. No filler, and the ambiguity note ("rather than guessed at") clarifies behavior rather than padding.

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?

Output schema exists, so return values need not be spelled out, and annotations are absent but the operation is obviously a read. The description covers the search-then-fetch workflow, the ambiguity path, and the input constraint. Minor gaps: no mention of what happens on zero results or how the default 500-row cap interacts with total_available/truncated beyond the schema text.

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%, so baseline is 3, but the description adds real semantics beyond the schema: the double-quote restriction on the search term and the cross-tool meaning of site_path (the value get_content requires, or null when ambiguous). limit/offset and kind are left entirely to their schema descriptions.

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?

States a specific verb and resource plus its scope: "Search content by name across every site the operator can see." The `kind` enum in the schema plus the name-substring framing separates it cleanly from siblings like find_computers, list_sites, and get_content — and it explicitly frames get_content as the follow-up call.

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 flow is clear: search here to obtain `id` + `site_path`, which is exactly what get_content consumes. It also explains when the result is unusable (site_path null on ambiguous site names). It gives no explicit negative guidance about when not to use it versus siblings such as search_inspectors or list_sites, but the context is unambiguous for the intended task.

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?

No annotations are provided, so the description carries the full behavioral burden. It implies a read via 'Get' and cites the underlying endpoint, but says nothing about permissions, error behavior, or whether the definition is live vs cached.

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?

One short, front-loaded sentence with no filler. It is appropriately sized, though extremely sparse.

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?

With an output schema present, return values need no explanation, and a single-parameter read tool is simple. Still, the absence of any annotation or usage framing leaves the safety and routing story thin.

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 single action_id parameter is documented there as a BigFix action ID. The description's '/api/action/{id}' phrasing only restates that id is a path parameter, adding little beyond the schema.

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 gives a specific verb (Get) and resource (an action's definition), so the purpose is clear. It does not distinguish this from siblings such as get_action_status or list_actions, leaving the agent to infer the boundary.

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 statement of when to use this tool versus get_action_status, list_actions, or get_content. Usage is only implied by the noun 'definition'.

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?

No annotations are provided, so the description carries the full burden. It does disclose a meaningful authorization constraint ('Status is scoped to the computers the configured operator can see') and the underlying endpoint, but it never explicitly states this is a read-only operation or how per-computer state is aggregated, leaving gaps for a no-annotation tool.

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 tight sentences: purpose first, then a memorable usage framing, then the scoping caveat. Front-loaded and waste-free, though the quoted framing sentence is more colloquial than informative.

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?

An output schema exists, so return values need not be explained, and the description covers purpose, the operator-visibility scoping, and a usage cue. With no annotations, a bit more behavioral detail (read-only confirmation, per-computer result shape) would round it out.

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 there is a single parameter, so the schema already documents action_id as a 'BigFix action ID.' The description's endpoint path ('/api/action/{id}/status') loosely ties {id} to action_id but adds no format or sourcing detail beyond the schema. Baseline 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 names a specific verb and resource ('Get an action's per-computer execution state') and pins the scope to per-computer state, which differentiates it from the sibling get_action (action-level metadata). It doesn't name get_action/list_actions explicitly, so differentiation is implied rather than stated.

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 framing 'The "did my change actually work" tool' gives real usage context (post-deployment verification). However, it never states when NOT to use this tool or routes the agent to the obvious alternatives (get_action, list_actions), so routing is left to inference.

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?

No annotations are provided, so the description carries the behavioral burden. It discloses the read endpoint and that the response contains the reported properties BigFix holds, implying a safe read, but says nothing about permissions, error behavior when the ID is unknown, or whether the record can be stale — gaps that matter for a lookup tool.

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?

Three short sentences: the action, what the payload contains, and the fallback guidance. Front-loaded with the core operation and free of 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?

With an output schema present, the description need not explain return fields, and it correctly focuses on identifying the record and the fallback path. It is nearly complete, missing only edge-case behavior (invalid/unknown ID, permission requirements).

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% and there is only one parameter, so the schema already documents computer_id as the BigFix computer ID. The description reinforces this via the /api/computer/{id} path but adds no new format or constraint detail beyond the schema.

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 a specific verb and resource ('Get one computer's full record') and pins the exact endpoint /api/computer/{id}, so the agent knows precisely what the tool returns. It also implicitly separates itself from find_computers by framing this as a single-record fetch keyed by ID.

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 gives an explicit routing rule: 'Use find_computers first if you only know part of the name,' naming the alternative sibling and the condition that selects it. It stops short of stating when not to use this tool (e.g., bulk retrieval), so it is clear but not exhaustive.

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?

With no annotations, the description carries the full burden, and it does disclose a real behavioral trait: it queries /api/computergroups/{site_path} directly and deliberately avoids besapi's mutable 'current site path' connection state, implying a stateless, side-effect-free read that requires the caller to supply the path. It does not cover permissions, error behavior, or missing-group handling, so it is good but not complete.

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 sentences with the core operation front-loaded; nothing is redundant. The second sentence is longer than needed for the point it makes (why besapi's helper is bypassed) but it does earn its place as rationale rather than 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?

An output schema exists, so return values need not be described, and both required params are fully documented. The remaining gap is behavioral: with no annotations, the description could state that this is a read-only operation and what happens on a nonexistent group, but it is otherwise sufficient to call 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?

Schema description coverage is 100%, so both parameters are already documented, including site_path format examples ('master', 'custom/MySite'). The description reinforces the 'by name / explicit path' semantics but adds no syntax or format detail beyond the schema, so the baseline 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?

States a specific verb (look up) and resource (computer group) plus the scoping constraint (by name, within an explicit site path). An agent can distinguish this from siblings like get_computer, find_computers, and get_content without opening any schema.

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 the retrieval context (named group under an explicit path) but never states when to use this versus alternatives such as get_computer or find_computers, nor any prerequisites. The second sentence explains an implementation choice rather than usage guidance, leaving routing to inference.

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?

No annotations are provided, so the description carries the full behavioral burden. 'Get' implies a read, but there is no disclosure of permissions required, error/not-found behavior, or any operational constraint. It adds nothing behavioral beyond what the schema implies.

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?

A single tight sentence, front-loaded with the verb and resource, with zero filler. Nothing needs trimming or reordering.

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?

An output schema exists, so return values needn't be explained, and this is a simple 3-param lookup. Still, with no annotations and no usage/behavioral guidance, the definition is only minimally complete for an agent deciding between this and find_content.

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 all three parameters are already documented in the schema, and the description merely restates the path-and-ID lookup. Baseline 3 applies when the schema does the heavy lifting.

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 a specific verb (Get) and resource (fixlet, task, analysis, baseline) plus the lookup keys (site path and ID). This is clear, but it never contrasts itself with the sibling find_content, so an agent must infer the direct-lookup-vs-search distinction.

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 by the retrieval mechanism: call it when you have a site path and content ID. But there is no explicit when-to-use/when-not framing and no mention of find_content as the alternative for search-based retrieval, leaving routing to inference.

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?

With no annotations, the description must carry the behavioral burden; it does disclose the key safety trait ("read-only"), which is valuable. However, it says nothing about authentication requirements, whether the dashboard must exist, or error behavior for missing variables, leaving gaps for a tool with zero annotation coverage.

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?

A single short sentence with the action and resource front-loaded and no filler. Every element earns its place.

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?

An output schema exists, so return values need not be explained, and both required parameters are covered by the schema. The description is nearly complete for a simple read tool, with only minor gaps around auth and failure modes.

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 both parameters (dashboard_name, var_name) are already documented in the schema. The description adds no format, casing, or lookup semantics beyond what the schema provides, 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?

States a specific verb ("Read") and resource ("BigFix dashboard datastore variable value"), so the agent knows exactly what it retrieves. It does not differentiate from any sibling, though none of the listed siblings covers dashboard datastore variables, so the ambiguity risk is low.

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 guidance on when to use this tool versus alternatives such as get_content or api_get, nor any prerequisite or context conditions. The only usage signal is the parenthetical "read-only", which describes behavior rather than when to call 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?

With no annotations, the description carries the full behavioral burden, yet 'look up' plus a unique name key already conveys read-only, single-entity semantics. It still omits permission requirements, behavior when the operator is not found, and whether the lookup is case-sensitive. 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.

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

A single sentence with zero filler, front-loaded with the verb and resource. Nothing to trim and nothing buried.

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?

An output schema exists, so return values need not be explained, and there is only one parameter. What is missing is the relationship to list_operators, which an agent choosing between the two would need. Minimum viable but visibly thin.

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 single user_name parameter is already documented. The description's 'by name' adds no syntax, format, or matching detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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?

States a specific verb (look up) and resource (BigFix operator / console user) and narrows scope to a single record by name. The parenthetical disambiguates 'operator' as a console user, which is genuinely useful domain context. It does not explicitly contrast itself with the sibling list_operators, so it falls 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?

'By name' implies single-record retrieval and implicitly contrasts with list_operators, but the description never names that alternative or states when to prefer one over the other. No prerequisites or conditions are given. Usage is inferable rather than stated.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the endpoint path (/api/serverinfo), which implies a read, but says nothing about authentication requirements, permissions, rate limits, or side effects. For a no-annotation tool this is a meaningful gap.

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?

A single short sentence that front-loads the verb and resource with zero filler. Nothing could be removed without losing 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?

The tool is a trivial zero-parameter getter and an output schema exists, so return values need not be described. The only shortfall is the absence of any auth or context note, which is minor for this operation.

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 takes zero parameters, so there is nothing for the description to clarify; the baseline of 4 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?

States a specific verb and resource ('Get BigFix root server info (version, etc)') and names the underlying endpoint, so an agent knows exactly what it retrieves. It does not explicitly differentiate itself from the generic sibling 'api_get', but the domain-specific framing makes the intent clear.

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 statement of when to use this tool versus alternatives such as api_get, whoami, or the other server-metadata siblings. The agent must infer usage entirely from the name and description.

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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose one meaningful trait — results are scoped to the configured operator's visibility — but says nothing about pagination, result volume, ordering, or read-only safety, leaving most behavioral questions unanswered.

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?

A single, front-loaded sentence with zero filler; the scope constraint and endpoint are packed into one clause and nothing is wasted.

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?

An output schema exists, so return values need not be described, and the parameterless schema is trivially complete. However, with no annotations and no usage guidance, an agent still lacks the safety profile and routing cues needed to confidently choose this over get_action.

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 takes zero parameters, so there is nothing for the description to clarify beyond the schema; baseline 4 applies. The endpoint reference adds no parameter meaning but no parameter gaps exist either.

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 a specific verb (List) and resource (actions) plus a scope qualifier ('visible to the configured operator') and even the backing endpoint. It is distinguishable from the sibling get_action (singular fetch), though it does not explicitly call out that distinction.

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 when-to-use guidance and no mention of alternatives such as get_action or get_action_status. The agent must infer that this is the enumeration tool and the others are detail/status tools purely from names.

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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose that results are scoped by the configured operator's visibility, which is useful. However, it does not state read-only safety, permission requirements, or other operational traits beyond the implicit 'List' verb.

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 front-loaded sentence with no filler. Every phrase contributes: the action, the resource, and the visibility scope.

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 zero-parameter schema and the presence of an output schema, the description covers enough for an agent to understand the tool's basic behavior. It does not need to explain return values, but it could be more complete by clarifying when this list is preferable to alternatives.

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 takes zero parameters, so there is nothing for the description to document. The baseline for a zero-parameter tool is 4, and the description appropriately avoids describing nonexistent arguments.

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 a specific verb and resource: 'List console operators.' It also adds scope with 'visible to the configured operator,' which helps distinguish it from a single-operator tool like get_operator. It does not, however, explicitly differentiate itself from sibling list tools such as list_roles.

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 guidance on when to use this tool versus get_operator, whoami, or other listing tools. The implied usage is simply that it lists operators, but no conditions, prerequisites, or alternatives 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?

With no annotations, the description carries the full behavioral burden. It does disclose one real trait beyond the name: results are filtered to what the configured operator can see, which matters for interpreting an empty or short list. It says nothing about ordering, size limits, or pagination, and offers no explicit read-only confirmation.

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?

A single front-loaded sentence with no filler, and the scoping constraint is placed before any potential alternative would be. It is efficient, though arguably too terse given that no usage or behavioral detail follows.

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, zero-parameter read tool with an output schema, so return-value documentation is not needed and the description need not carry much weight. What it says is sufficient to invoke correctly; only the absence of any usage routing and the lack of annotations keep it from being fully 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?

The tool takes zero parameters, so there is nothing for the description to clarify; the schema's empty object is self-explanatory. Baseline 4 applies per the zero-parameter rule.

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?

States a specific verb (List) and resource (BigFix roles), plus a meaningful scope qualifier: only roles visible to the configured operator. That scope distinguishes it conceptually from siblings like list_operators and list_sites, though those siblings are never named. Clear enough to act on, but no explicit sibling differentiation.

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 when-to-use guidance, no prerequisites, and no named alternative. An agent must infer from the name alone that this is the enumeration path for roles versus get_operator or whoami. The visibility qualifier hints at permission scoping but is not framed as usage advice.

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?

With no annotations, the description carries the full disclosure burden and does substantial work: it discloses the size-cap truncation behavior, that data becomes null with an explanatory note, and that the operator's visibility scope governs results. It still omits read-only confirmation and whether any pagination or auth is required.

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?

Front-loads the purpose well, but the second sentence restates the exact return envelope keys even though an output schema already exists, which is partially redundant. The truncation rationale is worth keeping; the key enumeration is not.

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 an output schema exists, the description need not explain return values, and it correctly focuses on the non-obvious truncation edge case and the visibility scope. The main gap is tying this tool to the broader site/content sibling set.

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 takes zero parameters, so the schema has nothing to document and the description has nothing to compensate for. Baseline for a no-parameter tool 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?

States a clear verb+resource ('List all sites') and adds the scoping qualifier 'visible to the configured operator'. It does not distinguish itself from siblings like find_content or get_content, which an agent might otherwise confuse with a site lookup.

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 on when to use this versus alternatives such as find_content or list_operators, and no prerequisites or exclusions. Usage is only implied by the tool name.

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?

With no annotations, the description carries the full burden and does so well: it discloses the exact side effect (writes new hosts to ~/.bigfix/remote_clients.toml), the probe sources, the negative constraints (never uses SSH discovery, never prompts), and the performance cost (can take minutes). Nothing about mutation behavior is left to inference.

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?

Front-loads the core action, then layers mechanism, constraints, performance, and usage guidance in short declarative sentences. Every clause earns its place, including the CLI analogy and the 'Evaluates nothing' caveat.

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?

Although an output schema exists and return values need not be explained, the description still names the returned fields (path, added, inventory). Combined with the side-effect, performance, and usage detail, an agent has everything needed to call this 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 takes zero parameters, so there is nothing for the description to disambiguate beyond what the empty schema already conveys. Baseline 4 applies for a parameterless tool.

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?

States a specific verb sequence (find/probe and add) over a specific resource (qna targets on the server's host) and names the concrete side effect against ~/.bigfix/remote_clients.toml. It is clearly distinguishable from siblings like qna_list_targets and qna_eval_client_relevance.

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?

Gives explicit triggering conditions: use when qna_list_targets shows no or too few inventory hosts, and clarifies the edge case that qna_eval_client_relevance only self-discovers when no inventory file exists. Names both alternative tools and the condition that selects this one.

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?

With no annotations, the description carries the full burden and does so richly: qna runs on lab targets not managed endpoints, no operator scope/site subscriptions/client settings, results differ from client_query for deployment-dependent inspectors, and an online_evaluator host receives the query. It also discloses error handling (per-target failures come as rows with error_kind, never tool errors), timing (discovering run can take minutes, first image use is slow), and the auto_discovery payload.

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?

Dense multi-paragraph text, but front-loaded with purpose and behavior. Nearly every sentence carries operational information, though it could be tightened slightly; the structure is logical rather than padded.

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 7-parameter tool with an output schema, and the description still covers the essential subtleties an agent needs: lab-vs-endpoint semantics, empty-target defaults, discovery behavior, and row-based error reporting. Nothing critical for correct invocation appears missing.

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%, so baseline is 3; the description adds value beyond the schema by explaining the default when both target parameters are empty (runs on every inventory host) and the consequence of naming targets (keeping a query off the online_evaluator host). It reiterates some schema content but the empty-parameter semantics are a genuine addition.

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?

States a specific verb+resource ('Evaluate CLIENT relevance with the BigFix qna tool') and immediately frames it as a fast lab feedback loop distinct from real deployment queries. Explicitly contrasts with client_query ('then confirm on real agents with client_query'), giving clear sibling differentiation.

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?

Gives explicit workflow: iterate on relevance syntax here, then confirm with client_query. Also documents the default behavior when inventory_targets/container_images are empty (runs on every inventory host), when to name targets to keep a query off the online_evaluator host, and when discovery vs. qna_discover_targets applies.

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?

With no annotations, the description carries the full behavioral burden and discloses the key side-effect profile: 'Listing never probes or writes anything.' It also explains auto_discovery_pending and discovery behavior on the next run, though it does not discuss permissions or output size.

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 purpose is front-loaded in the first sentence, and the remaining text is dense with useful behavioral context. It is somewhat long and explains output fields despite an output schema existing, but the sentences generally carry explanatory value.

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 zero-parameter listing tool with an output schema, the definition is complete: it explains the resource, the inventory source, discovery implications, container target policy, and that listing has no probing or writing side effects.

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 takes zero parameters, so there are no parameter semantics to document. The baseline for zero parameters is 4, and nothing in the description contradicts or obscures that.

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 a specific verb and resource: 'List targets available to qna_eval_client_relevance.' It also names related siblings such as qna_discover_targets and clarifies the inventory context, so the agent can distinguish this tool from nearby qna 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 clearly relates the tool to qna_eval_client_relevance and explains that calling a run without named targets uses every inventory host or triggers discovery when no inventory exists. It names qna_discover_targets as a related alternative, though it does not give an explicit 'call this instead of that when...' rule.

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?

With no annotations, the description carries the full burden and does so well: it discloses the offline/snapshot nature (no server call), the fuzzy match semantics, what is returned (signatures, result types, dialects), and an important reliability caveat that absence in the snapshot does not prove absence on the live server. These are exactly the behavioral traits an agent could not infer from 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.

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

Three tight sentences: identification and scope first, matching behavior and use-case triggers second, the snapshot caveat last. Zero filler and the most decision-relevant facts are 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?

The tool exposes an output schema, so return-value detail is correctly omitted. Given a 4-parameter read-only lookup, the description covers identity, matching semantics, usage triggers and the snapshot limitation — nothing an agent needs to invoke it correctly is missing.

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 kind, limit, query and dialect are already documented in structured data. The description's only marginal contribution is that results include 'the dialect each inspector exists in', which loosely relates to the dialect filter, but it adds no syntax or semantics beyond the schema. Baseline 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?

States a specific verb and resource ('Search the BigFix inspector reference') and immediately scopes it as an 'offline snapshot; no server call', which cleanly separates it from live-query siblings like analyze_relevance or client_query. It also characterizes the matching behavior (exact, prefix, near-miss) so the agent knows what kind of lookup this is before 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.

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

Gives two concrete trigger conditions: 'before writing a query' and 'after an is not defined error'. That is clear when-to-use guidance. It stops short of naming competitor tools (e.g. list_operators, get_operator) or stating when not to use it, so it lands at 4 rather than 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?

No annotations are provided, so the description carries the full burden and discharges it well: it discloses the absence of row-limiting relevance operators, that limit bounds the response not the work, and that results are scoped to the configured operator so counts are a lower bound unless is_main_operator. This is exactly the behavioral context an agent needs before trusting the output.

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?

Front-loads the purpose and example, then sequences the paging caveat and result-scope warning. It is somewhat long with four paragraphs, but each carries distinct operational information; only minor tightening is possible.

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 no-annotation, 3-param query tool, the description covers the query domain, paging semantics, response envelope, and the critical operator-scope caveat. Even though an output schema exists, the surrounding caveats make the definition complete for correct invocation and interpretation.

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%, so the schema already documents limit/offset/relevance, putting the baseline at 3. The description adds genuine meaning beyond the schema by explaining why limit/offset are necessary (the relevance operators are undefined) and clarifying that limit constrains the response rather than the evaluation work.

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?

States a specific verb+resource ('Evaluate a BigFix session relevance query on the root server') and immediately distinguishes it from client-side siblings by noting 'no client round-trip'. An agent can separate this from client_query/client_query_submit without opening either schema.

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?

Explains the context in which this applies (server-side data: computers, fixlets, actions, sites) and gives concrete usage guidance for paging (use limit/offset). It doesn't explicitly name the sibling to use for client-side evaluation, relying on the 'no client round-trip' phrase to imply the contrast.

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?

With no annotations present the description must carry the behavioral burden, and it does the key part: 'Makes no server call' tells the agent this is a purely local, side-effect-free operation requiring no server auth. It also frames the failure mode (malformed/non-conforming XML). Return format is left to the existing output schema, which 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.

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

Three short lines: purpose, a crucial behavioral note, and the usage trigger. Front-loaded, no filler, every sentence earns its place.

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 single-input, local validation tool with an output schema and no annotations, the description covers what it does, when to invoke it, and its non-networked nature. Nothing an agent needs to call it correctly is missing.

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?

One parameter at 100% schema description coverage, so the schema already documents 'bes_xml' fully. The description adds no syntax, format, or size guidance beyond what the schema provides, making the baseline 3 correct.

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?

States a precise verb ('Validate') and resource ('BES XML') plus the standard it validates against ('the BigFix schemas'). No sibling tool performs validation, so it is trivially distinguishable from the get_/list_/find_ 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?

Gives explicit timing ('Use before asking anyone to import content') and a concrete rationale (catches malformed XML locally instead of as a REST error). It does not name alternatives or when-not-to-use, but no sibling overlaps this function, so that gap is minor.

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?

With no annotations, the description carries the full burden and does well: it explains that writes_enabled indicates whether gated write tools are registered at all, and that is_main_operator determines whether other tools' results are complete BigFix state or a scoped view. That is meaningful behavioral context beyond a trivial identity call, though it says nothing about auth requirements or failure modes.

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 purpose is front-loaded in the first sentence, followed by focused explanations of two non-obvious fields. It is slightly verbose but every sentence adds real information, so nothing is wasted.

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?

An output schema exists, so return values need not be enumerated, and the description still clarifies the two fields whose semantics an agent would otherwise misread. For a zero-parameter diagnostic tool, nothing needed to invoke it correctly is missing.

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 takes zero parameters, so there is no parameter semantics to document and the baseline of 4 applies. The description instead adds meaning to the returned fields (writes_enabled, is_main_operator), which is a plus rather than a gap.

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?

States a specific verb and resource ('Show the configured connection') and enumerates exactly what it returns: user, root server, main operator status. This is clearly distinguishable from get_server_info or list_operators, though it never names a sibling explicitly, which keeps it 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?

'Cheap connectivity and permission smoke test' gives a clear usage context for when to reach for this tool. It does not state when-not to use it or point at alternatives, so it falls short of the explicit routing a 5 requires.

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