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

Annotations already declare readOnlyHint=false and destructiveHint=true, and the description reinforces this with 'All methods are allowed,' flagging that mutating verbs are reachable. However it omits genuinely useful context the annotations do not cover: whether the token's scopes restrict what can be called, how upstream error statuses are surfaced, and that mutations here bypass the validation of dedicated tools.

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, front-loaded with purpose then the usage restriction. 'All methods are allowed' is mildly redundant with the method enum but usefully signals the tool's breadth, so it largely 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?

With no output schema, the description should say something about what comes back, and it does not (raw JSON passthrough? error shape?). For a destructive-capable proxy tool, an agent also benefits from knowing whether it validates paths or scopes. The core purpose and usage rule are present, so it is adequate but with clear gaps.

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 75% and the schema already documents path format with an example, query JSON-string encoding, and the method enum with a GET default. The description adds only that the request is authenticated 'with the configured token,' which explains the absence of a token parameter but nothing about the parameters themselves. Baseline 3 fits.

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 ('send a raw request to the panel REST API') and immediately scopes it against the ~150 sibling tools with 'Use it only for endpoints no dedicated tool covers.' An agent can tell exactly what this tool is and is not for 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?

Gives a clear negative selection rule ('only for endpoints no dedicated tool covers'), which is the key routing decision for an escape-hatch tool. It does not name specific alternatives, but with a sibling list this size that is impractical; a preference hint such as 'prefer read-only use' would have earned a 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?

Annotations declare readOnlyHint=false and destructiveHint=false, which the description does not contradict. The description adds genuine behavioral context beyond the annotations by disclosing the authentication constraint (admin JWT only, API-key forbidden), which is exactly the kind of operational detail the annotations cannot convey.

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 with the core action front-loaded and the auth caveat following. No wasted words; the definition is easily parsed.

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?

No output schema exists, and the description does not explain what is returned (e.g., whether the token secret is revealed only once), which is a notable gap for a token-creation tool. Still, it covers the purpose and the critical auth constraint needed to invoke 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 all three parameters (name, scopes, expiresInDays) are already documented in the schema. The description adds no parameter-level meaning 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 and resource ("Create a new API token"), so an agent immediately knows the operation. It does not explicitly differentiate from siblings like api_tokens_list or api_tokens_delete, but the create action is unambiguous from the name plus description.

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?

Provides one important usage precondition: the endpoint is forbidden via API-key and requires an admin JWT-token. However, it offers no guidance on when to use this versus api_tokens_list (e.g., check for existing tokens first) or any workflow context.

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?

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation risk is covered structurally. The description adds genuinely new behavioral context beyond that: the authentication constraint (admin JWT only, API-key forbidden), which affects whether an agent can invoke it at all. It does not say whether deletion is recoverable or what happens to the credential immediately.

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, zero filler, with the action front-loaded and the constraint immediately behind it. Nothing needs to be reordered or trimmed.

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 one-parameter destructive call with annotations covering the safety profile and no output schema required, the description supplies the action plus the critical auth gate. It is largely complete; an explicit statement of irreversibility or whether the token is immediately invalidated would close the remaining 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 description coverage is 100% and there is exactly one parameter (uuid) whose format and meaning are fully documented in the schema. The description adds no parameter-level detail, so the schema carries the burden and a 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 opens with a specific verb+resource pair, "Delete API token," which is unambiguous and clearly distinct from siblings like api_tokens_create, api_tokens_list, and api_tokens_scopes. It never explicitly names an alternative or scope boundary, so it differentiates by resource name rather than by exclusion.

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 states an explicit precondition for invocation: the endpoint is forbidden via "API-key" and usable only with an admin JWT-token. That is real usage guidance an agent must honor before calling. It stops short of when-to-use/when-not guidance relative to siblings (e.g. revoke vs delete semantics).

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, giving the safety profile. The description adds meaningful behavioral context beyond that: the authentication requirement (admin JWT only, not API-key), which is a real gate on invocation. It doesn't mention pagination or return shape, but the auth disclosure is substantive.

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, front-loaded with the primary action before the auth caveat. Efficient and readable, with only minor awkwardness in the quoting of "API-key".

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 read-only listing, the description covers purpose and the critical auth constraint. No output schema exists, but a list-returning endpoint needs little explanation of return shape; nothing essential to invoking 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 and schema coverage is 100%, so there is nothing for the description to document. Baseline for a no-parameter tool is 4.

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+resource ('Get all API tokens'), clearly distinguishing it from siblings like api_tokens_create, api_tokens_delete, and api_tokens_scopes. It does not explicitly name those siblings, but the list semantics are unambiguous.

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 provides an explicit usage constraint: forbidden via API-key, must be used with an admin JWT-token. This tells the agent the conditions under which the call will succeed, though it doesn't name alternatives or say when to prefer a more filtered listing.

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?

Annotations already declare readOnlyHint=true/destructiveHint=false, so safety is covered. The description adds meaningful context beyond that: the authentication constraint (admin JWT only, not API-key) and the shape of what is returned (scopes grouped by resource).

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, front-loaded with the purpose, followed by return shape and the auth restriction. No filler or redundancy.

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, annotation-covered read tool with no output schema, the description supplies everything an agent needs: what it returns, how it's organized, and the caller authentication required to invoke it.

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 per the rubric the baseline is 4. There is nothing for the description to disambiguate, and it correctly signals a parameterless catalog read.

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 available API token scopes') and clarifies the return content ('catalog of scopes that can be granted to an API token, grouped by resource'). This clearly separates it from siblings like api_tokens_list/create/delete, which operate on tokens rather than the scope catalog.

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?

Provides the key selection context that this is the read path for discovering grantable scopes (implicitly feeding api_tokens_create), and explicitly states the access constraint 'Forbidden via API-key, admin JWT only.' It does not name a sibling alternative outright, but the when-to-use context is clear.

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?

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. Beyond that, the description adds nothing — no indication of whether it hits the network, whether it validates the supplied API key, or what constitutes a 'valid' vs 'invalid' status. With annotations present the bar is lower, but zero added context earns only a 2.

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 no waste and the key concept front-loaded. It is efficient, though the brevity tips into under-specification rather than crispness.

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?

There is no output schema, so the description carries the burden of conveying what comes back — yet it gives no indication of the return shape (boolean authenticated, token expiry, user identity, scopes). For a diagnostic tool whose whole value is the returned status, this is a real 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?

The tool takes zero parameters, so the baseline is 4; there is no parameter semantics to describe and the schema is trivially complete.

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 verb and resource ('Get the status of the authentication'), so it is not a bare tautology, but 'the authentication' is vague: it doesn't say whose auth (API key? current session? global system auth state?) or what 'status' comprises. No sibling tool overlaps this name, so differentiation is not the problem — specificity is.

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 precondition (e.g., 'call before other operations to verify the API key is valid'), and no mention of alternatives. The agent must infer the trigger condition entirely.

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?

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing further: no aggregation granularity, no scoping, no note on whether the result is per-node or totaled, and no indication of result size behavior despite the topNodesLimit parameter.

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?

Five words, front-loaded, no filler or redundancy. However, brevity here reflects under-specification rather than disciplined conciseness; the single phrase has no room to earn its place beyond restating the name.

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?

There is no output schema, so the description would need to characterize what the tool returns, and it does not; 'usage' is left undefined. Given a three-parameter analytics tool sitting among many overlapping bandwidth siblings, an agent lacks enough context to invoke it confidently or interpret its results.

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%: start, end, and topNodesLimit all carry their own descriptions and formats, so the schema does the heavy lifting. The description's 'by Range' only loosely gestures at the date parameters and adds no syntax, timezone, or limit semantics beyond what the schema already states. 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 restates the tool name ('bandwidth_nodes_usage' -> 'Get Nodes Usage') and adds only the modifier 'by Range', which merely echoes the required start/end dates. It gives no indication of what 'usage' means (traffic, bytes, requests, connections) and does nothing to separate it from bandwidth_node_users, bandwidth_nodes_users, bandwidth_nodes_usage_threshold, bandwidth_user_usage, or bandwidth_squad_usage.

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 stated conditions, and no mention of any alternative. With roughly a dozen bandwidth/system stat siblings in the list, an agent has no basis in the description for choosing this tool over bandwidth_nodes_users or system_bandwidth_stats.

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?

Annotations already declare a safe read operation, so the bar is lower; the description adds genuinely useful behavior beyond that — a ~2 minute data-flush latency caveat that tells the agent results may lag by up to two minutes, and an exact restatement of the aggregation rule (total usage over the period on the given nodes).

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, front-loaded with the core purpose and with no filler. Sentence 2 slightly restates sentence 1's threshold idea, a minor redundancy, but it earns its place by tying the rule to the minTotalBytes parameter.

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?

There is no output schema, but the description tells the agent what is returned (the set of users meeting the threshold). It stops short of describing the return fields (e.g., identifier and usage amount) or any result cap, which would fully close the gap for a 4-parameter query 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 3 baseline applies, but the description adds real meaning: minTotalBytes is applied to the user's total usage summed across the given nodes over the period, not per-node, which is aggregation semantics the schema does not express.

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 (Get) plus resource (users exceeding a traffic threshold) and scope (on the given nodes for a period), which distinguishes it from the other bandwidth_* siblings that lack a threshold concept. It does not explicitly name an alternative tool, so it falls just short of the top score.

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 threshold framing implies when the tool is useful (finding heavy users), and the flush-latency note implies when the data is not suitable, but there is no explicit when-to-use vs. when-not guidance or reference to siblings like bandwidth_nodes_usage.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that: it does not say how the date range scopes the results, how many records come back, or what 'topUsersLimit' actually controls.

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 no filler and the scoping key front-loaded. It is efficient, though its brevity is partly under-specification rather than disciplined trimming.

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 four-parameter read tool with no output schema and a confusingly similar sibling set, the description is far too thin. It should at minimum clarify what is being aggregated, how the date window applies, and what topUsersLimit does.

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 only 50%: 'start' and 'end' are documented in the schema, but 'nodesUuids' and 'topUsersLimit' have no description anywhere. The only parameter-related text ('by Nodes UUIDs') merely restates the required array param already visible in the schema, and the semantics of the top-N limit are left entirely unstated.

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 verb ('Get'), a resource ('Nodes Users Usage') and a scoping key ('by Nodes UUIDs'), so the general shape is understandable. However, 'Nodes Users Usage' is ambiguous — it could mean per-user traffic on nodes or top-user rankings per node (the 'topUsersLimit' param hints at the latter) — and it makes no attempt to distinguish itself from the near-identically named sibling 'bandwidth_node_users' or from 'bandwidth_nodes_usage'.

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 at all. Given siblings such as 'bandwidth_node_users', 'bandwidth_nodes_usage', 'bandwidth_user_usage' and 'bandwidth_squad_user_usage', the agent has no stated basis for choosing this tool over the others.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds nothing beyond that — it does not say the result is a ranking of top users, whether topUsersLimit truncates results, or how the start/end window is interpreted. With annotations carrying the safety profile, the remaining behavioral burden is unaddressed.

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 phrase, so nothing is wasted and the keying parameter is front-loaded. But its brevity is under-specification rather than discipline — the phrase carries too little information to be a useful definition.

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 4-parameter, 3-required analytics tool with no output schema and only 50% schema coverage, the description leaves the return shape (top-users list?) and the meaning of topUsersLimit and the date window unstated. Too incomplete for the tool's complexity.

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 only 50%: uuid and topUsersLimit have no schema descriptions. The description only gestures at the uuid parameter ("by Node UUID") and says nothing about topUsersLimit's role in limiting/ranking returned users, which is the one parameter that most changes behavior.

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?

"Get Node Users Usage by Node UUID" names a verb and resource and keys it to the node UUID parameter, so the basic operation is inferable. However, "Node Users Usage" is vague — it does not say the usage is bandwidth, nor does it distinguish this from siblings like bandwidth_nodes_usage or bandwidth_user_usage, so an agent cannot confidently pick it without reading 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?

There is no when-to-use guidance at all: no mention of the date-range requirement, how it differs from bandwidth_nodes_usage (whole-node) or bandwidth_user_usage (per-user across nodes), and no exclusions. The agent must infer selection entirely from the 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely non-schema context: that the listing is threshold-filtered, that scope is restricted to nodes reachable through the squad's inbounds, and — most valuable — that usage data is only flushed to the database roughly every 2 minutes, which tells the agent results can lag. It stops short of describing pagination or the shape of returned user records.

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 compact sentences, front-loaded with the core purpose and followed by the most decision-relevant detail. Minor noise: "on the given nodes" references nodes that are not actually a parameter, which slightly muddies an otherwise efficient phrasing.

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 a fully described six-parameter schema and no output schema, the description covers what an agent needs: what is returned, the inclusion threshold, the node scoping derived from the squad, and the data-freshness caveat. Nothing about correct invocation is left unresolved, aside from sibling disambiguation handled in the usage dimension.

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 every parameter is already documented in the schema. The description restates minTotalBytes semantics ("total usage over the period on the given nodes is >= minTotalBytes") but adds no format, unit, or edge-case detail beyond it, 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 and resource: "Get internal squad users traffic usage for a period," and clarifies the result scope (users above minTotalBytes, limited to nodes reachable via the squad's inbounds). However, it does not distinguish itself from the near-identically named sibling bandwidth_squad_user_usage or from bandwidth_user_usage, so an agent still has to guess which of the two squad-usage tools 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?

There is no when-to-use, when-not-to-use, or alternative-tool guidance at all. Given a sibling literally named bandwidth_squad_user_usage plus bandwidth_user_usage and bandwidth_nodes_usage, the absence of disambiguation is a real selection hazard rather than a minor omission.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful operational context — zero-filled days and a ~2 minute flush cadence — but also asserts a minTotalBytes threshold that does not exist in the schema, which muddies the behavioral picture.

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?

Purpose is front-loaded and the sentences carry real information, but the minTotalBytes sentence is wasted at best and misleading at worst, and 'Get a single user' conflicts with 'Returns users whose total usage...', signaling a list result.

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 no output schema, the description does explain return semantics (per-day, zero-filled, threshold-filtered), which is valuable. However the singular/plural mismatch leaves the cardinality of the result ambiguous, and the phantom threshold parameter is unexplained.

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 75% (userId is undocumented), so the description should compensate, yet it says nothing about userId and instead introduces minTotalBytes, a parameter absent from the schema. That phantom parameter can send an agent hunting for an argument it cannot supply, which is worse than silence.

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 a single user daily traffic usage on the internal squad nodes for a period.' This distinguishes it from squad-level (bandwidth_squad_usage) and node-level (bandwidth_nodes_users) siblings, though no sibling is named explicitly. The scope 'internal squad nodes' is concrete.

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 when-to-use guidance, no prerequisites, and no mention of alternative tools such as bandwidth_squad_usage or bandwidth_user_usage for other granularities. The agent must infer applicability from the resource name alone.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered externally. The description itself adds no behavioral context beyond that – no return shape, no pagination, no mention of what the topNodesLimit affects – so it contributes nothing over the structured fields.

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 fragment with no wasted words, but it is under-specified rather than genuinely concise – it is effectively a restated title rather than a purposeful one-liner.

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 four-parameter read tool with no output schema, the description is far too thin: it omits what is returned, how the range and topNodesLimit shape the result, and any usage context. Annotations cover only the safety hint, so the description should do more.

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 75%, with userId, start, and end documented in the schema, but topNodesLimit has no description at all. The description provides no parameter meaning whatsoever, leaving the undocumented parameter unexplained in both places.

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 phrase 'Get User Usage by Range' restates the tool name (bandwidth_user_usage) and only adds the notion of a date range. It conveys a read of per-user bandwidth over a time window, but it does not differentiate from close siblings such as bandwidth_squad_user_usage or bandwidth_node_users, which an agent must distinguish by name alone.

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 when-to-use guidance, no prerequisites, and no mention of alternatives like bandwidth_squad_user_usage. Usage is only weakly implied by the 'by Range' phrasing.

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?

Annotations already state readOnlyHint=false and destructiveHint=false, telling the agent this is a non-destructive mutation. The description adds nothing beyond that: no permission requirements, no uniqueness or duplicate-handling behavior for providerUuid+billedAt, and no disclosure of side effects such as provider balance recalculation.

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 four-word sentence is certainly concise and front-loaded, but brevity here is under-specification rather than efficiency — there is no second sentence to carry any of the missing behavioral or parameter context.

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 mutation tool with no output schema, 33% schema coverage, and three required parameters, the description is too thin. An agent cannot determine required permissions, duplicate-handling rules, or what the created record's identifier looks like from this definition.

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 only 33% — billedAt is documented in the schema, but providerUuid and amount carry no description in either place. The description says nothing about these parameters, so it fails to compensate for the coverage gap in a tool where providerUuid (which provider the entry belongs to) and amount semantics matter.

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 verb 'create' plus resource 'billing history' makes the basic operation identifiable and distinguishable from siblings billing_history_list and billing_history_delete. However, 'infra billing history' is oddly phrased and the description never explains what a billing history record represents (a charge entry? a line item tied to a provider?), leaving the purpose only partially 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?

No guidance on when to create a billing history entry versus alternatives, no prerequisites, and no mention of related siblings such as billing_provider_get or billing_node_create. The agent must infer all usage context from the name alone.

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?

The annotations already declare destructiveHint=true and readOnlyHint=false, and the description merely restates 'Delete' without adding anything beyond that. It does not say whether the deletion is permanent/irreversible, what the uuid identifies, or what protections or permissions apply.

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 words, front-loaded with the verb, so there is no padding to trim. But the terseness is under-specification rather than efficiency for a destructive one-parameter tool.

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 destructive tool with no output schema and an undocumented parameter, the description leaves key facts unstated: permanence of deletion, what the uuid selects, and any prerequisite step. An agent could call it, but not confidently.

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 0% for the single uuid parameter, and the description does not compensate by explaining what the uuid refers to (a billing history entry). The bare 'infra billing history' phrase gives no mapping between the parameter and the record to delete.

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 ('Delete') and resource ('infra billing history'), which distinguishes it from the sibling billing_history_create and billing_history_list. It does not, however, say what a single deletion targets (a record identified by uuid) or add any differentiation beyond what the name already conveys.

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 when-to-use, when-not-to-use, or alternative guidance is given. The destructive nature is never acknowledged, and there is no hint about confirming intent or using billing_history_list first to find the target record.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds nothing beyond that—no note on pagination, authentication requirements, or what the returned history contains. It is consistent with the annotations but contributes almost no behavioral context of its own.

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 wasted words. While extremely terse, it is structurally clean and appropriately sized for a simple read tool, though it leaves no room for useful scoping details.

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 description is minimally complete for a simple read-only list with full schema documentation and safety annotations. It still lacks sibling disambiguation and does not describe the return shape or pagination behavior, which are minor gaps given the schema and annotations.

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 both parameters (size, start) are fully documented in the schema. The description mentions no parameters and adds no meaning beyond what the schema already provides, making the baseline 3 appropriate.

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 (Get) and resource (infra billing history), so the agent can identify it as a read/list operation. However, it does not explicitly differentiate from siblings like billing_history_create/delete or billing_providers_list, leaving some ambiguity about scope.

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?

Provides no guidance on when to use this tool versus its siblings, such as billing_history_create, billing_history_delete, or other billing list tools. An agent must infer usage from the name alone.

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?

Annotations declare readOnlyHint=false and destructiveHint=false, which tells the agent this is a non-destructive write. Beyond that the description adds nothing: it does not say whether the referenced provider/node must pre-exist, whether the call is idempotent, what happens on duplicate nodes, or what a successful creation returns.

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 phrase is four words with no structure to speak of. It is not verbose, but as with a bare one-word description, the problem is under-specification rather than conciseness — for a four-required-parameter mutation tool this is far too terse to front-load anything useful.

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?

A four-parameter, all-required mutation tool with 25% schema coverage and no output schema needs the description to explain the relationship between provider, node, and billing schedule. The description supplies none of that, leaving the agent to infer the entire semantics of the 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?

Schema description coverage is only 25% (only nextBillingAt is documented), so the description carries the burden for providerUuid, nodeUuid, and name — and it says nothing about them. It does not explain that providerUuid/nodeUuid are references to existing billing providers and nodes, nor what the nextBillingAt timestamp drives.

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 verb (Create) and a resource (billing node), so the basic operation is inferable. However, "infra billing node" is vague domain jargon, and nothing distinguishes this from siblings like billing_nodes_list, billing_node_update, billing_node_delete, or billing_provider_create — the agent must guess whether 'infra billing node' means a billing-enabled node, a provider association, or something else.

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 indication of when to use this tool versus the many adjacent billing and node tools (billing_nodes_list, billing_node_update, billing_provider_create, nodes_create). No prerequisites, no exclusions, no alternatives are mentioned.

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?

The annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds nothing beyond the word 'Delete' — no indication of irreversibility, whether associated billing history or node records are cascaded, or what authorization is required. For a destructive mutation, this is a meaningful gap even with the lower bar set by 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?

It is a single front-loaded fragment with no filler, which is good, but it is under-specified rather than genuinely concise. There is no room wasted, yet no useful structure or detail is provided either.

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 destructive, one-parameter tool with no output schema and no annotation detail beyond hints, the description should carry more weight — consequences, scope of deletion, and parameter meaning. It leaves all of that 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 description coverage is 0%, and the description never references the single required parameter. The agent must infer that 'uuid' identifies the billing node to delete purely from the schema's type and format, with no confirmation of whether it is the node UUID or a billing-record UUID.

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?

It names a specific verb (Delete) and resource (infra billing node), so the basic operation is identifiable. However, it does not differentiate from adjacent siblings such as nodes_delete, billing_history_delete, or billing_node_update, and the term 'infra billing node' is not clarified anywhere. An agent cannot tell from the text alone whether this targets a Remnawave node record or a billing-specific entity.

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 mention of alternatives. With siblings like billing_history_delete and nodes_delete in the list, the description should explain which entity this removes versus those, but it offers nothing.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds essentially nothing beyond that: no pagination behavior, no filtering/scope limits, no indication of how many nodes or what fields come back. It is close to a restatement of the name.

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 no filler, and the resource is front-loaded. It is efficient, though the brevity borders on under-specification rather than true conciseness.

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 simple (no params, read-only annotations), but there is no output schema, so the agent has no idea what a 'billing node' record contains. The description does not fill that gap or note whether results are paged, leaving it minimally viable.

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. 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?

The phrase 'Get infra billing nodes' does name a verb and a resource, so the agent can tell it is a read/list operation over billing node entities. However, it never clarifies how this differs from the very similar 'nodes_list' or from 'billing_history_list'/'billing_providers_list', and 'infra billing nodes' is a loosely defined object. Adequate but with clear sibling-differentiation gaps.

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 at all: no statement of when to call this versus nodes_list, billing_providers_list, or billing_history_list, and no prerequisites. The agent must infer usage purely from the 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?

Annotations already establish readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that: it doesn't say whether the update is partial or full-replacement, what happens on unknown UUIDs, whether the operation is idempotent, or what permission level is needed.

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 clause with no filler or redundancy. It is efficient, though its brevity borders on under-specification rather than tight conciseness.

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 mutation tool that reschedules billing across a set of nodes, the description omits essential context: what field is being changed, whether it is a bulk operation, side effects, and error behavior. Annotations cover safety but not operational semantics, and there is no output schema to fill the 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 description coverage is 0%, so the description carries the burden of explaining 'uuids' and 'nextBillingAt'. It mentions neither, nor does it explain the array semantics (bulk update) or the date-time format expectations. Only the self-explanatory parameter names provide any signal.

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+resource ('Update ... billing nodes'), so an agent knows this mutates billing node records. It does not differentiate itself from siblings like billing_node_create or billing_node_delete, but the tool name and the verb+resource combination make the purpose legible.

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 mention of alternatives such as billing_node_create, billing_node_delete, or billing_nodes_list. The agent must infer usage entirely from the 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?

Annotations already declare readOnlyHint=false and destructiveHint=false, covering the basic safety profile. The description adds no behavioral context beyond that: no auth requirements, no uniqueness/duplicate-name behavior, no statement about what is created or returned.

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 words is not conciseness but under-specification; the single fragment is front-loaded but earns no informational value beyond the tool name.

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 mutation tool with no output schema, zero schema coverage, and three undocumented parameters, the description is far too thin. It does not tell the agent what is required (the 'name' field) or what constitutes a valid provider.

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 0% and the description mentions no parameters. The three fields (name with min/max length, loginUrl, faviconLink) are entirely undocumented, leaving the agent to guess formats and constraints.

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 verb and a resource ('Create infra provider'), so the operation type is clear. However, the resource is named 'infra provider' while the tool and siblings are named 'billing_provider_*' and a separate 'billing_node_create' exists, so the agent cannot be confident whether this creates a billing provider or a node-level infra entity.

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 when-to-use guidance at all. Nothing distinguishes this from billing_node_create or tells the agent what preconditions (e.g., existing provider listing via billing_providers_list) must hold before creating.

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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so irreversibility is largely covered by structured data. The description adds nothing beyond the identifier — it does not say whether the delete is permanent, what happens to billing nodes/history referencing the provider, or whether the call fails if dependencies exist.

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. It is terse to the point of under-specification, but nothing in it 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?

This is a destructive mutation with no output schema and no annotations beyond the destructive flag, so the description should carry the burden of dependency/irreversibility context. It delivers none, leaving an agent unable to predict side effects on related billing resources.

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?

With only one parameter and 0% schema description coverage, the phrase 'by uuid' is the sole signal, and it does tell the agent the identifier is a UUID rather than a name or numeric id. Beyond that it adds no format, validation, or sourcing guidance, so it sits at the 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 specific verb (Delete) and resource (infra provider, identified by uuid), which is enough for an agent to distinguish it from the get/create/update/list siblings. It does not explicitly name those alternatives, and the term 'infra provider' sits slightly at odds with the 'billing_provider_*' namespace, but the intent is unambiguous.

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 statement of when to use this versus billing_provider_update (e.g., deactivate vs. remove) or billing_providers_list, and no prerequisites such as whether dependent billing nodes must be cleared first. Usage is only implied by the verb.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond those annotations: it does not mention auth requirements, error behavior, or what the call returns. No annotation contradiction.

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 terse sentence with zero wasted words and the key info front-loaded. It is appropriately sized for a one-parameter lookup, though it could be slightly more structured.

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 simple one-parameter read, the description plus annotations cover the essential action and safety. However, with no output schema it does not say what is returned or how not-found errors behave, leaving some contextual gaps.

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 0%, so the description must compensate, and it only names 'uuid' as the lookup key. That is a marginal semantic addition over the schema, which already declares a required uuid string with uuid format.

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 (Get) and resource (infra provider) plus the lookup key (uuid), so the fundamental action is clear. It does not explicitly distinguish itself from the sibling billing_providers_list or billing_provider_create/update/delete, keeping it from 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 description gives no guidance on when to use this tool versus alternatives such as billing_providers_list or billing_provider_create. No prerequisites or context conditions are 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered by structured data. The description adds nothing beyond that: no note on whether results are paginated, how many providers are returned, or whether the list needs auth scoping.

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 four-word sentence with no padding and the scope word front-loaded after the verb. It is efficient, though arguably under-specified rather than genuinely concise.

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-argument read-only list tool with annotation coverage, the essentials are present. With no output schema, a hint about what the returned provider objects contain or how many to expect would round it out, but the gap is modest.

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 and the baseline is 4. The description's 'all' correctly signals there are no filter inputs.

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 ('Get') and resource ('providers') scoped to everything ('all'), which distinguishes it from the singular sibling billing_provider_get. Minor friction: the description calls them 'infra providers' while the tool and siblings use 'billing provider', so terminology does not perfectly align.

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 word 'all' implies this is the unfiltered list tool to use when no specific provider is targeted, which is enough to route the agent away from billing_provider_get. However, no alternative is named explicitly and there are no stated conditions or exclusions.

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?

Annotations declare a non-destructive write, and the description adds nothing on top: it does not say whether this is a full replace or partial update, whether the uuid target must already exist, what permissions are required, or what happens to omitted fields. For a mutation tool the description carries meaningful unanswered behavioral questions.

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?

It is short, but this is under-specification rather than conciseness: a three-word fragment with no front-loaded distinction between required and optional fields or return behavior. Brevity here costs information rather than saving it.

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 four undocumented parameters, no output schema, and no description-level behavioral detail, an agent cannot confidently construct a call. Everything an agent needs beyond the bare field names is absent.

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 0% across four parameters (name, uuid, loginUrl, faviconLink), and the description mentions none of them. No format, constraint, or validation context is supplied beyond what the raw schema types already show.

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?

"Update infra provider" restates the tool name with only the thinnest verb+resource framing and never says what a provider entity actually holds or which fields become mutable. Against siblings like billing_provider_create/delete/get, it gives no distinguishing detail beyond the operation word.

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 mention of alternative siblings such as billing_provider_create or billing_provider_delete. The agent is left to infer applicability entirely from the 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?

Annotations already state readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive write. The description adds nothing beyond that: no note on whether name collisions fail, whether tags/inbounds must be set separately, or what the created profile returns. With annotations present the bar is lower, but the description contributes essentially zero 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.

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

Four words with no padding and the verb is front-loaded, which is structurally fine. But at this length the brevity reads as under-specification rather than efficiency, especially given the free-form config payload.

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 has a nested, unconstrained object parameter, no output schema, and no annotations beyond the safety hints. The description supplies none of the missing guidance an agent needs to construct a valid 'config' payload or understand the result, so it is incomplete for the tool's complexity.

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 0% and the description says nothing about either parameter. Critically, 'config' is a nested free-form object with empty properties and additionalProperties allowed, meaning the agent has no idea what keys or structure to supply. This is the exact case where the description must compensate, and it does not.

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 ("Create config profile"), so the basic operation is unambiguous. However, it offers no differentiation from close siblings like config_profiles_update or config_profiles_get, and nothing about what a 'config profile' contains. Clear but minimally viable.

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 mention of prerequisites (e.g. that name must be unique, that a profile typically needs inbounds/tags afterwards), and no routing to or away from siblings. The agent is given no context for selecting this tool over alternatives.

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?

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered. The description only restates 'Delete' and adds nothing beyond the annotations – no note on permanence, cascading effects on nodes using the profile, or failure conditions.

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?

Extremely short and waste-free, but the brevity is under-specification rather than disciplined conciseness – it is a two-word restatement of the name.

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 destructive mutation tool with no output schema, the description omits what an agent needs: whether deletion is irreversible, whether profiles attached to nodes can be deleted, and what a successful or failed call returns.

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% with a single well-documented uuid parameter ('UUID of the config profile'), so the schema carries the semantic load. The description adds no format, lookup, or resolution detail beyond it, which is the baseline-3 case.

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?

Names a specific verb and resource ('Delete config profile'), so an agent can distinguish it from siblings like config_profiles_update or config_profiles_create. However, it offers no differentiation among the many other delete tools in the ecosystem (squads_delete, hosts_delete, etc.) beyond the resource name.

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, and no prerequisites stated. It does not say whether the profile must be detached from nodes first, nor what happens if the UUID is in use.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds no further behavioral context such as required permissions, error behavior, or what the returned profile contains.

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 wasted words. It is appropriately sized for a simple get-by-identifier operation.

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 simple read operation, the description identifies the resource and lookup key, which is enough to invoke the tool correctly. However, it provides no output shape and no routing guidance among the several config_profiles_get* siblings, leaving some gaps.

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 0%, so the one uuid parameter has no schema-level documentation. The description says 'by uuid', which identifies the parameter's role but adds no constraints or format details beyond the type and format already in 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 (Get) and resource (config profile) and the lookup key (uuid). It does not explicitly distinguish itself from sibling tools such as config_profiles_get_computed_config or config_profiles_get_inbounds, so it is clear but lacks 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 guidance on when to use this tool versus alternatives like config_profiles_list or config_profiles_get_computed_config. The description only restates the basic operation, leaving usage context implied at best.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds one behavioral nuance—that the config profile is 'computed' rather than raw—but omits auth, caching, computation timing, or reproducibility details.

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?

Extremely concise and front-loaded: one imperative clause with no filler. For a single-parameter lookup, nothing is wasted, though the brevity contributes to gaps captured in other dimensions.

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?

Adequate for a simple read-only lookup: annotations cover safety, the schema covers the single required field, and no output schema means return values need not be described. Still, the key sibling distinction (computed vs raw config profile) is absent, so completeness is only minimal.

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 0%: the only parameter is a required uuid string with no schema description. The description merely restates 'by uuid' and does not explain the UUID's source, expected format beyond the schema's format, or its role in selecting the profile.

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 ('Get'), a specific resource ('computed config profile'), and the required key ('by uuid'), so the core action is clear. However, it does not differentiate this computed-profile variant from sibling config_profiles_get, so an agent cannot infer the distinction from the description alone.

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?

Provides no when-to-use guidance, no exclusions, and does not name config_profiles_get or config_profiles_get_inbounds as alternatives. Usage is only implied by the name and UUID parameter, leaving the agent to infer the intended scenario.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing further — no note on whether the profile must exist, whether the result is paginated, or what an inbound record contains.

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. It is tight, though the brevity edges toward under-specification rather than optimal economy.

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 one-parameter read tool with no output schema, the definition is minimally viable but thin: it doesn't describe the returned inbound structure or ordering, and there are many sibling get/list tools it could have been disambiguated from.

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%: the single uuid parameter is fully documented in the schema as "UUID of the config profile". The description only restates that the uuid selects a profile, adding no syntax, format, or edge-case 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?

The description pairs a specific verb ("Get") with a specific resource ("inbounds") and a scope qualifier ("by profile uuid"), so the operation is unambiguous. However, it never names the closely related siblings config_profiles_get or inbounds_list, so an agent must infer the division of labor from names alone.

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 over inbounds_list (list all inbounds) or config_profiles_get (get the profile itself). The scoping phrase implies a use case but no alternative or exclusion is 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful response-shape context: the xray config is deliberately omitted from the default payload, which tells the agent what it will and won't receive. It stops short of describing pagination, ordering, or payload size for what is presumably a large list.

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, zero waste. The inclusion/exclusion scoping is front-loaded and the routing information follows immediately, so the most decision-relevant facts come first.

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 no output schema, the description carries the burden of describing the return shape, and it does disclose the key contents (inbounds and nodes) and the key exclusion (xray config). It omits ordering, pagination, and volume expectations for a list endpoint, which is a minor but real 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 description coverage is 100% and the single parameter's schema text already explains that full returns the raw panel response including config and rawInbound. The description's 'or full=true' merely re-frames that same fact as a use case, adding little semantic 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 and resource (list config profiles) and immediately scopes what is included (inbounds and nodes) and what is not (the xray config). It differentiates itself from the sibling config_profiles_get and from its own full=true mode, so an agent can tell it apart 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?

Explicitly names the alternative for a single profile ('use config_profiles_get for one profile') and the alternative mode for getting the omitted xray config ('or full=true'). The condition that selects each alternative is stated, leaving nothing 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?

Annotations declare readOnlyHint=false and destructiveHint=false, so the safety profile is partially covered. Beyond that, the description says nothing about whether the supplied list must contain all profiles or only the moved ones, whether positions are absolute or relative, or whether the operation is idempotent — all material for a mutation 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?

At three words it is maximally front-loaded and wastes nothing, but this is under-specification rather than true conciseness — the brevity removes information the agent needs rather than trimming redundant text.

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 mutation tool with an undocumented nested-array payload, no output schema, and annotations covering only read/write safety, the description should at minimum explain the reorder semantics (full ordering vs. partial moves). It is not complete enough to call the tool confidently.

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 0% for the single, non-trivial "items" array parameter. The description never mentions the uuid/viewPosition payload, its ordering semantics, or the maximum position range, so it fails to compensate for the schema's silence on meaning.

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 pairs a specific verb ("Reorder") with a specific resource ("config profiles"), so an agent knows the operation type without opening the schema. It does not differentiate itself from config_profiles_update or explain that this affects display/ordering position, 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?

There is no statement of when to use this tool versus config_profiles_update or the other *_reorder siblings. The name implies a reordering intent, but the description offers no prerequisites, no conditions, and no exclusions.

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?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: it does not say whether existing tags are overwritten, whether the call is idempotent, or what happens to the profile's other settings.

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 verb and resource front-loaded and no filler. It is efficient, though its brevity is partly under-specification rather than genuine crispness.

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 mutation tool with two required parameters, 0% schema description coverage, and no output schema, this description is far too thin. Replacement-vs-merge behavior, required uuid, and tag constraints all go unexplained.

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 0%, so the description carries the full burden and fails to compensate. It mentions 'tags' only implicitly via the word 'tags' and never mentions the required 'uuid' parameter, the tag character pattern, or the 10-item cap that the schema enforces.

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 verb ('Set') and resource ('Config Profile'), so the domain is clear, but it never clarifies whether 'set' replaces the existing tag list or merges into it, nor does it distinguish this from sibling config_profiles_update. It is adequate but leaves a real ambiguity an agent would care about.

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 when-to-use guidance, no mention of the natural alternative (config_profiles_update or config_profiles_tags_list), and no prerequisites such as needing the profile uuid. The agent must infer usage purely from 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that—it doesn't say whether it returns all distinct tags across profiles, pagination, or ordering—so it is adequate but thin against an already-covered behavior surface.

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 clause with no filler or redundancy. It is arguably too terse rather than verbose, but every word earns its place and the verb-resource ordering is correct.

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, read-only list tool with no output schema, the description is minimally sufficient to identify the call. It leaves open whether tags are global or per-profile and what the response contains, which is acceptable but not 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 schema declares zero parameters, so there is nothing for the description to disambiguate. 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 ('Get') and resource ('tags of Config Profiles'), so an agent knows it returns tag data for the config-profile domain. It does not distinguish itself from sibling list/get tools such as config_profiles_list, config_profiles_get, or config_profiles_set_tags, which is the main gap.

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 when-to-use, no when-not-to-use, and no mention of alternatives such as config_profiles_get or config_profiles_set_tags. The agent must infer the context entirely from the 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?

Annotations only declare it is a non-read, non-destructive write. The description adds real behavioral context beyond that: the config is replaced in full (not merged) and 'Nodes that use the profile restart xray to apply it,' a meaningful side effect. It still omits permission requirements and whether partial config edits are possible.

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, zero filler, with the action and its scope front-loaded before the side-effect note.

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 3-parameter mutation tool with a nested object, no output schema, and 0% schema coverage, the description covers purpose, replacement semantics, and the node-restart consequence. It is nearly sufficient, missing only per-parameter detail (especially the required uuid) and any permission caveats.

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 0%, so the description carries the burden. It clarifies that the 'config' argument is the 'full' xray config (replacement semantics), which adds value beyond the bare object schema, but leaves the required 'uuid' and the 'name' constraints entirely to 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?

States a specific verb and resource ('Update a config profile') and enumerates the mutable fields (name and/or the full xray config), which implicitly distinguishes it from tag-oriented siblings like config_profiles_set_tags. It does not explicitly name any sibling, 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?

The description implies when it applies (changing a profile's name or config) but gives no explicit when-to-use/when-not-to-use guidance or alternative routing, e.g. pointing tag changes to config_profiles_set_tags. Usage 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?

Annotations declare readOnlyHint=true and destructiveHint=false, and the description adds the non-obvious async behavior: it starts a job and returns a jobId rather than the data inline. This is meaningful context beyond the annotations. It doesn't detail job lifetime or polling, but the key behavioral trait is disclosed.

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, front-loaded with the purpose followed immediately by the action and the follow-up tool. No wasted words.

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 one-parameter async tool with no output schema, the definition covers purpose, the job-based mechanism, and where the result lives. The plural 'node(s)' phrasing is a small ambiguity, but 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?

With a single parameter at 100% schema coverage, the schema already documents nodeUuid, so the description adds nothing parameter-specific. The only note is a minor mismatch: the description says 'node(s)' plural while the schema accepts a single nodeUuid. 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 ('Request the active connections on a node') and explicitly distinguishes itself from the companion tool connections_by_node_result. An agent knows exactly what this tool does and how it differs from the result/other connection siblings.

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?

Describes the async job pattern and names the alternative for retrieving the outcome ('fetch the outcome with connections_by_node_result'), which is strong next-step routing. It doesn't clarify when to prefer this over connections_by_user_request, but the workflow guidance is clear.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that: it does not explain that the jobId originates from a separate request call, whether results may still be pending, or how the result set behaves.

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 phrase with no wasted words. Its terseness is efficient, though it borders on under-specification given the tool's role in a request/result pair.

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 one-parameter read tool with annotations covering safety and no output schema, the description is minimally adequate. However, it omits the crucial async context (that the jobId comes from connections_by_node_request), which is exactly the kind of information a 'result' tool needs.

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 0%, so the description must carry the parameter burden. It clarifies that jobId is a job identifier used as the lookup key, which is useful, but adds nothing about format, source, or valid ranges beyond the parameter name.

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 (Get) plus resource (Connections for Node) and the lookup key (by Job ID), so an agent knows it retrieves node connection data keyed on a job. It does not distinguish itself from the sibling connections_by_node_request, leaving the request/result relationship to inference, 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?

No when-to-use guidance and no mention of alternatives such as connections_by_node_request, which is presumably what produces the jobId. The async pairing is only weakly implied by the word 'result' in the name, not stated in the 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?

Annotations declare a safe read (readOnlyHint=true, destructiveHint=false), and the description adds the important non-obvious trait that the operation is asynchronous — a job is started on the node(s) and a jobId is returned. That async contract is exactly the kind of behavior annotations cannot express and is the main reason an agent would otherwise misuse the tool. It does not mention latency, per-node fan-out behavior, 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?

Two sentences, zero filler, and the core purpose is front-loaded ahead of the follow-up instruction. Every clause earns its place by either defining the operation or directing the next call.

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 one-parameter async read tool with no output schema, the description supplies the essentials: what is returned conceptually (active connection IPs), that a jobId comes back, and where to fetch results. It is slightly thin on the multi-node aspect ('node(s)') and any timing expectations, but nothing critical 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 0% for the single userId parameter, so the description must compensate. It only implies the identifier via 'of a user' and adds no format, type, or resolution guidance (e.g. numeric ID vs uuid) beyond what the schema already declares. For a trivial single-identifier param this is acceptable but not additive.

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 — 'Request the active connections (IPs) of a user' — which cleanly separates it from the node-scoped sibling connections_by_node_request. It also names its result companion, so an agent can place it in the workflow without opening schemas. It stops short of 5 only because the distinction from the node variant is implied by 'of a user' 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?

Gives clear workflow context: this call starts a job and the outcome must be retrieved via connections_by_user_result. That is actionable routing guidance. It does not, however, state when to prefer this over connections_by_node_request or connections_geocheck_request, so there is no explicit alternative-selection 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that: it does not explain that this consumes a job ID produced by connections_by_user_request, whether the job must be complete, or how pending/failed jobs are handled.

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 no filler, front-loading the retrieval key. It is efficiently stated, though the brevity comes at the cost of the missing context noted elsewhere.

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 read tool with one undocumented parameter and no output schema, the description is very thin. It omits the essential async-job relationship to connections_by_user_request and connections_by_node_result, which is the key context an agent needs to call it 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 0% for the single jobId parameter, so the description must carry weight. "by Job ID" does at least connect the parameter to the job concept, but adds no format, source, or validity detail beyond what the property name already implies.

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?

"Get Connections for User by Job ID" names a verb (get) and a resource (connections for a user) and adds the lookup key (job ID). However, it largely restates the tool name and does not distinguish itself from its close siblings connections_by_user_request and connections_by_node_result, so an agent cannot tell this is the result/retrieval half of an async job pattern.

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 connections_by_user_request (the request that presumably produces the job ID) or connections_by_node_result. The pairing is only inferable from the name, not the 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?

Annotations already flag destructiveHint=true and readOnlyHint=false, so the safety profile is partially covered by structured data. But for a destructive operation that terminates live sessions, the description says nothing about impact (immediate disconnect of active users/IPs), reversibility, or scope of effect, leaving 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?

It is short and front-loaded with the action, so there is no wasted text. However, this brevity stems from under-specification rather than disciplined concision, so it does not earn a high score.

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 a two-parameter, destructive, nested-schema tool with no output schema, the description is far too thin. It omits when to use it, what the parameters mean, and what the destructive action actually does, leaving the agent to infer nearly everything from the schema alone.

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 0% and the description mentions only 'Users or IPs' generically, with no explanation of the dropBy / targetNodes oneOf branches. The nested schema consts (allNodes, specificNodes, userIds, ipAddresses) carry most of the meaning, and the description adds nothing beyond the users/IPs mention.

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 phrase 'Drop Connections for Users or IPs' gives a verb (drop) and resource (connections) and hints at the two targeting modes (users/IPs). However, it reads as a title fragment rather than a stated purpose, and it does not differentiate itself from the read-side siblings like connections_by_user_result or connections_by_node_result beyond the word 'drop'.

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 the sibling connection-lookup tools, no prerequisites, and no warning about the destructive action. The only usage cue is the imperative verb 'Drop', which an agent must interpret on its own.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds important non-obvious behavior: it starts an async job on the node(s) and returns a jobId rather than the final result, which the agent must know before calling.

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 written sentences with no waste. The purpose is front-loaded and the async follow-up instruction comes second, matching how an agent reads and acts on it.

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 three-parameter async job-starter with no output schema, the description covers what an agent needs: what is checked, that a job starts, that a jobId is returned, and which tool retrieves the result. No critical calling information 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% (nodeUuid, ip, interface each have descriptions), so the schema carries the parameter semantics. The description does not add meaning beyond what the schema already provides, making the baseline 3 appropriate.

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: checking how a node's exit IP is geolocated. It cleanly distinguishes itself from the sibling connections_geocheck_result and from other connections tools by focusing on geolocation of an exit IP rather than listing connections.

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 tells the agent to call this tool to start the geolocation check and explicitly routes it to connections_geocheck_result to fetch the outcome. It lacks an explicit when-not statement or comparison to other connections_* job starters, but the async workflow condition is clear.

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?

Annotations declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. Beyond that the description adds nothing: for a job-result tool the critical behaviors are whether the job may still be pending, whether results expire, or whether the call blocks, and none of these are disclosed.

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

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

A single short, front-loaded sentence with no filler. It is efficient, though the brevity is partly under-specification rather than tight editing.

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?

No output schema, no annotations beyond readOnly, and no parameter documentation in the schema. For a tool whose entire value is retrieving the outcome of a prior request, the definition omits the request/result relationship and the state of the returned result, leaving the agent to guess at the workflow.

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 0% for the single jobId parameter, so the schema gives no type/format/source context. The description does add real meaning by tying jobId to a Job (implying it comes from the request call), but it stops short of naming the source tool or the ID format.

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 verb ('Get') and a resource ('Geocheck for Node') qualified by 'Job ID', which is more than a tautology. But 'Geocheck' is unexplained jargon and the description never signals that this is the result-fetching half of an async pair with connections_geocheck_request, so an agent cannot cleanly distinguish it from that sibling.

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 when-to-use guidance at all. There is no mention of the connections_geocheck_request tool that presumably creates the job, nor of when the result is ready, so the agent must infer the two-step flow entirely from naming conventions.

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?

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is carried by structured data. The description adds only the "EVERY user" scale emphasis and says nothing about whether existing members are preserved, whether the operation is undoable, or what volume of users it touches — leaving the destructive mass-mutation semantics largely unelaborated.

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 no filler, and the scope keyword is front-loaded. The capitalized "EVERY" is mildly stylized but functional, 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?

For a one-parameter tool with annotations and no output schema, the definition is minimally sufficient, but for a destructive all-users bulk operation it omits key context such as reversibility and the effect on current squad membership. An agent can call it, but cannot fully predict the blast radius.

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 the single uuid parameter is fully documented in the schema as the external squad identifier. The description adds no information about the parameter (e.g. that it targets the squad being populated), so this is the baseline 3 where the schema does all the 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?

The description states a specific verb ("Add") and resource ("an external squad") plus the scope ("EVERY user"), so an agent immediately knows this is a mass-membership mutation rather than a per-user add. It does not name the counterpart external_squads_remove_all_users, so it falls short of full sibling differentiation, but the purpose is unambiguous.

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 statement of prerequisites, and no mention of the alternative (adding specific users, or the remove_all counterpart). The agent gets no help deciding between this global operation and a targeted membership change.

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?

Annotations only declare that this is a non-read-only, non-destructive write. The description adds nothing beyond that: no mention of permissions, whether names must be unique, whether the new squad is empty, or what a successful call returns. For a mutation tool with no output schema, that is a real 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?

At three words it is maximally front-loaded and wastes nothing, but the terseness is under-specification rather than efficiency — there is no content to trim because almost nothing was said.

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?

A write tool with an undocumented required parameter, no output schema, and ambiguous positioning against the `squads_*` and other `external_squads_*` siblings. The description does not supply enough context for an agent to invoke it confidently.

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 0%, so the single `name` parameter is documented only by its regex and length bounds. The description does not mention the parameter at all, so any naming constraints or semantics beyond the pattern are left to the agent to reverse-engineer.

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 ('Create') and resource ('external squad'), so the basic action is unambiguous. However, it does not explain what an 'external squad' is or how it differs from the sibling `squads_create`, leaving the agent unable to tell the two resources apart beyond the name.

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 `squads_create` or any other sibling, nor any stated prerequisites (e.g., required scopes or that the squad is for external users). The agent must infer all selection criteria.

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?

Annotations already declare readOnlyHint=false and destructiveHint=true, so the bare word 'Delete' restates what structured data already provides. The description adds no context about irreversibility, whether members/assignments are orphaned on delete, or required permissions.

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 phrase that is trivially front-loaded and wastes no words. However, its brevity here reflects under-specification rather than efficient communication of needed detail.

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 one-parameter delete with a complete schema and annotations covering the safety profile, the minimum is met and no output schema needs explaining. It still omits any caveat about permanence or side effects, which a destructive operation would benefit from.

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 the single uuid parameter is fully documented in the schema, so the schema does the heavy lifting. The description adds no syntax, format, or semantic detail beyond it, making 3 the correct 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?

Clear specific verb+resource: 'Delete external squad'. The 'external' qualifier implicitly separates it from the sibling squads_delete, but the description never states that distinction explicitly, so the agent must infer it from the name alone.

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 when-to-use, prerequisites, or alternative guidance. With both squads_delete and external_squads_delete present, the description offers nothing to route the agent between them or to warn that deletion is intended for externally-managed squads.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that — no note on error behavior for unknown UUIDs, permissions, or what an 'external squad' is.

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 no filler, and the resource is front-loaded. It is arguably too terse rather than bloated, which the other dimensions penalize.

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 one-parameter read by UUID the definition is minimally sufficient, and the annotations cover safety. However, with no output schema there is no indication of what a returned squad contains, so the description could do more for a fetch 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 description coverage is 100% and the single uuid parameter is fully documented with format=uuid, so the schema carries the weight. The description only restates that the lookup is by uuid, adding no new meaning; 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 (get) and resource (external squad) keyed by uuid, and the 'external_' prefix distinguishes it from the sibling squads_get. It is clear but does not itself explain how an external squad differs from a regular squad.

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 squads_get, external_squads_list, or the other external_squad endpoints. The reader must infer that it is the single-item fetch counterpart to external_squads_list.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, which fully covers the behavioral risk profile of a zero-parameter listing tool. The description adds nothing beyond that (no scope, ordering, or pagination context), but also contradicts nothing, so it sits at the minimum-viable 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?

A single short sentence with zero filler, front-loaded on the verb and resource. It is terse but not padded, though it borders on under-specification rather than true efficiency.

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 trivial zero-param list tool this is nearly adequate, but with no output schema the description does not indicate the shape of the returned collection (e.g. an array of external squads with tags), and it never clarifies its relationship to the internal squads toolset.

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, which is the baseline-4 case: there is nothing for the description to disambiguate, and the empty schema is self-explanatory.

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 clear verb ("Get") and resource ("external squads"), so an agent knows exactly what is returned. However, it offers no differentiation from closely named siblings such as squads_list (internal squads) or external_squads_get, leaving the distinction to the tool name alone.

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 external_squads_get, squads_list, or external_squads_tags_list. No prerequisites, exclusions, or alternatives are mentioned, so usage must be inferred entirely from the 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is carried by structured data. The description's 'EVERY' adds a genuine behavioral nuance (full sweep vs. subset), but it says nothing about reversibility, whether the squad itself survives, or authorization 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?

A single front-loaded sentence where the scope qualifier 'EVERY' arrives before the object, with zero filler or redundancy. Nothing could be trimmed without losing the one distinction that matters.

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 one-parameter tool whose annotations already flag destructiveness and which returns no structured output, the description is minimally sufficient. However, a bulk destructive operation warrants at least a note on irreversibility or post-condition (e.g., squad remains but is emptied), which is absent.

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?

There is a single required parameter with 100% schema description coverage ('UUID of the external squad'), so the schema already does the work. The description adds no format, sourcing, or lookup guidance beyond what the schema states, which matches the baseline 3 for a fully documented parameter.

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 (remove), resource (external squad), and scope ('EVERY user'), which cleanly separates it from subset-removal siblings like squads_remove_many_users. It does not explicitly name or contrast itself with the near-identical squads_remove_all_users or external_squads_add_all_users, so an agent must infer the difference from the resource noun alone.

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 when-to-use guidance, no prerequisites, and no alternatives are offered. There is no guidance on when to prefer external_squads_add_all_users or a subset-removal tool, nor any warning about irreversibility before an all-users purge.

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?

Annotations cover only readOnlyHint=false and destructiveHint=false, so the description still owes the agent an explanation of what reordering actually does. It does not say whether the 'items' list must be complete, whether omitted squads keep their position, or how 'viewPosition' is interpreted — all essential for a mutation.

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 words, front-loaded and waste-free, but the brevity is under-specification rather than economy — there is no second sentence to add value because no value was added.

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?

A mutation tool with no output schema, no meaningful annotations beyond the safety hints, and a 0%-documented nested parameter cannot be invoked correctly from this description alone; the agent knows neither the payload contract nor the 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?

Schema description coverage is 0% for a nested array parameter whose element shape (uuid + viewPosition pair) carries the entire semantics of the operation. The description never mentions the items array, the required fields, or whether the list is a full replacement, so it fails to compensate for the coverage 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 verb and resource ('Reorder external squads'), so the basic intent is legible. However, it offers no scope detail and no differentiation from the very similar sibling squads_reorder (internal squads), leaving the agent to infer the distinction from the name alone.

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 mention of alternatives such as squads_reorder or the other *_reorder siblings. The agent must guess the intended context entirely.

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?

Annotations already declare readOnlyHint=false and destructiveHint=false, covering the basic safety profile. The description adds no behavioral context, such as whether existing tags are overwritten, what permissions are required, or what the return behavior is, so it provides little beyond the 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?

The single sentence is front-loaded with the verb and contains no wasted words, but it is under-specified rather than appropriately concise. For a mutation tool, this brevity leaves critical usage and parameter details unstated.

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 a 2-parameter mutation tool with no output schema and minimal annotations, the description should cover usage guidance and parameter meaning. It covers neither, and the annotations only address safety, so the definition is incomplete for correct agent invocation.

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 0%, so the description must compensate but does not. It mentions 'tags' generically and never addresses uuid, nor does it explain the tags pattern, maxItems, or maxLength constraints, leaving both required parameters semantically undocumented.

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 'Set tags of External Squad' states a specific verb and resource, making it distinguishable from sibling set_tags tools for other resources. However, it lacks scope details such as whether tags are replaced or appended, and it does not mention the uuid parameter, so it falls short of the highest clarity.

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 indication of when to use this tool versus alternatives like external_squads_update or external_squads_get. The description provides no context, prerequisites, or exclusions, leaving usage entirely 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing further: it doesn't say whether this returns the global tag vocabulary across all external squads or tags for a specific squad, nor anything about ordering or pagination.

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 four-word sentence with no filler and the resource front-loaded. It is efficient, though borderline under-specified rather than deliberately compact.

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 no output schema, no parameters, and a trivial read operation, the description is close to sufficient, but it leaves the scope of the returned tag set genuinely ambiguous for an agent that must decide how to use the result.

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 and the baseline of 4 applies. No parameter knowledge is missing that the description could supply.

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 ('Get') and resource ('tags of External Squads'), which is enough to distinguish it from the many sibling tag-list tools (squads_tags_list, nodes_tags_list, hosts_tags_list). It stops short of explaining what the tag collection actually represents, but the resource is unambiguous.

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 offers no when-to-use context, no prerequisites, and no reference to alternatives such as external_squads_set_tags or squads_tags_list. An agent must infer from the name alone that this is a read-only listing call.

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?

Annotations only declare readOnlyHint=false and destructiveHint=false, which tells the agent it is a non-destructive mutation but nothing more. The description adds no behavior: it does not say whether this is a partial (PATCH) or full-replace update, whether omitted fields are cleared, or what permissions are required for a 10-parameter mutation.

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 single sentence is technically concise with no filler, but it is under-specified rather than economical — three words that carry no information beyond the tool name.

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?

A 10-parameter mutation with nested objects, 10% schema coverage, and no output schema requires a description to carry the load, and this one is empty. An agent has no basis to invoke the tool correctly beyond passing a UUID.

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 10% (only uuid is documented), yet the description explains none of the nine other parameters: name, templates, hwidSettings, customRemarks, hostOverrides, subpageConfigUuid, responseHeadersAdd/Remove, and subscriptionSettings. With nested objects and no compensating prose, an agent cannot know what these fields mean or how to populate them.

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?

"Update external squad" is essentially a restatement of the tool name external_squads_update. It names a verb and resource but provides no scope, no hint of what parts of the squad are updatable, and no differentiation from sibling squads_update or external_squads_set_tags.

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 external_squads_set_tags, external_squads_reorder, or the internal squads_update. No prerequisites or context are given, leaving the agent to guess from the name alone.

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?

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered structurally. The description adds nothing beyond that: it does not say whether deletion is permanent, whether it cascades to related records, or how partial failures are handled, which matters for a destructive bulk operation.

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 words, front-loaded with the verb and resource, no filler. The brevity is efficient, though it shades into under-specification rather than tight conciseness.

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 destructive bulk mutation with no output schema and 0% parameter documentation, the description should carry more: batch limits, irreversibility, partial-success behavior. Annotations cover only the destructive flag, so key operational detail 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 0% and there is one parameter. The phrase 'by UUIDs' restates what the schema already encodes via property name 'uuids' and format 'uuid', adding no format, ordering, or limit semantics beyond structured data.

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 ('Delete hosts') plus the identifier type ('by UUIDs'), so the agent knows exactly what operation is performed. It does not distinguish itself from siblings like hosts_delete (single) or hosts_bulk_disable, leaving the bulk-vs-single routing to be inferred from the name alone.

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 bulk delete versus the singular hosts_delete, nor any stated preconditions, limits on batch size, or confirmation requirements. The agent must infer usage entirely from 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?

Annotations declare readOnlyHint=false and destructiveHint=false, so the safety profile is partly covered, but the description adds nothing: it does not say whether disabling is reversible, whether it affects active connections, or how partially invalid UUID lists are handled in a bulk operation.

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; it is appropriately sized for the operation, though there is essentially nothing beyond the minimum statement.

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 one-parameter mutation with no output schema and a bulk scope, the description is adequate but thin — it omits reversibility, bulk failure semantics, and any permission requirement.

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 0%, so the description must carry the param burden. 'By UUIDs' correctly identifies the input as a list of host identifiers, but adds no format, limit, or failure-mode detail beyond the schema's uuid array type.

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?

Names a specific verb ('Disable') and resource ('hosts'), plus the scoping mechanism ('by UUIDs'), so it is immediately distinguishable from hosts_bulk_enable and hosts_bulk_delete. It stops short of explicitly contrasting with those siblings.

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 when-to-use guidance, no mention of the single-host counterpart or the enable/disable pairing. The bulk nature is implied only by the name and the plural 'UUIDs'.

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?

Annotations already establish this is a non-read, non-destructive write, so safety is partly covered. The description adds nothing beyond that: no idempotency, no permission requirements, no partial-failure behavior for a batch call, and no statement of what 'enabling' actually changes on a host.

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 verb and scope come first. It is efficient, though its brevity is part of the problem rather than a virtue here.

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 bulk mutation tool with no output schema and no annotation coverage of operational details, the description should say something about batch semantics, failure handling, or resulting state. None of that is present.

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?

There is only one parameter and schema description coverage is 0%, so the description must carry the load. 'By UUIDs' does identify the identifier type, but the schema already declares format: uuid, leaving no added detail on array limits, batching, or behavior for unknown IDs.

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 (enable), resource (hosts), operation mode (bulk) and identifier type (UUIDs), which is enough to distinguish it from hosts_bulk_disable or hosts_bulk_delete by name alone. It does not explicitly call out the sibling it complements, but the purpose is unambiguous.

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 mention of the natural alternative (hosts_bulk_disable) or how this differs from single-host or non-bulk enabling. The intended usage is only inferable from the 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?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation/safety profile is covered. The description adds the genuine bulk trait that the fields are applied to every host in `uuids`, but says nothing about partial-failure handling, reversibility, or whether fields merge vs. replace — relevant for a bulk mutation with no output 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?

A single tight sentence with the scope constraint front-loaded and zero filler. It is efficient, though arguably under-sized for a 32-parameter bulk mutation.

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 complex bulk mutation with 32 parameters, 3% schema coverage, no output schema, and no annotations describing outcomes, the description is too thin. It leaves the bulk semantics (per-host application, failure behavior, field semantics) largely to inference.

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 only 3% across 32 parameters, so the schema does essentially no work and the description carries the full burden. Pointing to hosts_update for the field semantics is a clever compensation, but it only names `uuids` and gives no syntax or detail for the 31 other parameters.

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 (Update), resource (hosts), and scope (many at once), and explicitly ties the field semantics to the sibling hosts_update. An agent can distinguish it from the singular hosts_update and from other bulk host operations like hosts_bulk_enable/delete.

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: 'many hosts at once' signals this is the bulk counterpart to hosts_update, and 'same as hosts_update' anchors which fields apply. However, it never states when to prefer this over hosts_update, nor any exclusions or preconditions for the bulk path.

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