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

With no annotations, the description carries the burden well: it discloses that it writes to /etc/hosts, that no sudo is required, that entries are isolated in a managed block, and that the write is reversible via later cleanup. It stops short of saying whether an existing hostname mapping is overwritten or what the call 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?

Three short sentences, each earning its place: what it does, when to use it, and how its effects are scoped/reversible. The key fact (no sudo) is front-loaded in the first sentence.

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 mutation of a system file with no annotations and no output schema, the description covers the essentials: where it writes, privilege requirements, scoping, and reversibility. Overwrite semantics for pre-existing hostnames are the one notable omission.

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

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

Schema coverage is 100%, so baseline is 3; the description adds conceptual grounding by explaining the 'managed block' that the tag parameter's 'bulk cleanup' grouping relies on. That link between the tag and the cleanup lifecycle is real value beyond the schema text.

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 pair ('add or update') plus the exact resource and location ('HTB host entry in /etc/hosts'), which is unambiguous. It does not explicitly name the sibling it complements (e.g. htb_hosts_remove/htb_hosts_clean), but the verb is distinct enough from the other hosts_* tools.

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

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

'Use this whenever you need a hostname like machine.htb to resolve to a box IP' gives a concrete triggering condition with an example. It hints at the cleanup sibling ('can be cleaned later') but does not explicitly state when to prefer remove/clean/show instead.

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

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

With no annotations, the description carries the full burden. It does disclose a genuine lifecycle trait — the snapshot is never auto-pruned — but says nothing about where the backup is written, whether repeat calls create duplicates, or whether permission errors are possible for a write operation on /etc/hosts.

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

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

One sentence, front-loaded with the action and target, with the non-pruned guarantee appended as a parenthetical. No filler.

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

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

For a one-optional-param tool with no output schema, the description is close to sufficient, but it omits the return value (an identifier or filename an agent would need to later call htb_hosts_restore or htb_hosts_list_backups) and where the snapshot lives. Those are the remaining gaps an agent must discover empirically.

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

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

Schema coverage is 100% and the single 'label' parameter is described as an optional label for the backup filename, so the schema does the work. The description adds nothing about how the label affects filename collisions or ordering, so the baseline 3 applies.

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

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

States a specific verb ('Save') and resource ('snapshot of /etc/hosts'), which cleanly separates it from siblings like htb_hosts_restore, htb_hosts_list_backups and htb_hosts_clean. It does not name a sibling explicitly, but 'explicit snapshot' implies a deliberate manual backup versus any automatic copy.

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

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

The phrase 'explicit snapshot' and '(never auto-pruned)' imply the tool is for intentional, permanent backups before risky changes, but no when-to-use/when-not statement or alternative is given. An agent must infer that this is the pre-change safety step from the presence of htb_hosts_restore and htb_hosts_clean.

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

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

With no annotations, the description carries the burden and does reasonably well: it discloses that the operation mutates a file, that the no-argument form destroys the entire block, and that dry_run previews without writing. It does not mention reversibility or the existence of the backup/restore siblings, which would matter for a destructive 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?

Front-loaded with the core action, then one clause per mode, then the exclusivity rule, then dry_run. Dense and mostly waste-free, though the mode enumeration and the exclusivity sentence could be merged for tighter structure.

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?

Covers all four optional parameters, the destructive default case, and the preview path, which is close to sufficient for a 4-param mutation tool with no annotations and no output schema. What's absent is what the operation returns and whether backups are taken automatically.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds genuine meaning on top by tying `match` to htb_hosts_select's semantics, framing `exclude` as its inverse keep-list, and declaring the three selection parameters mutually exclusive. Only `dry_run`'s interaction with the other modes (e.g. combined with no args) is left implicit.

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?

Opens with a specific verb+resource ("Remove managed host entries") and then enumerates the four operating modes, so the agent knows exactly what the tool does. It does not, however, differentiate itself from the sibling htb_hosts_remove, which an agent could easily confuse with this tool.

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?

Each mode's selection condition is spelled out (no args = full block, tag = exact tag, match = htb_hosts_select semantics, exclude = inverse keep-list) and mutual exclusivity is stated explicitly. Missing is any guidance on when to prefer this over htb_hosts_remove, or any prerequisite/confirmation 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?

No annotations exist, so the description must carry the load; 'List available' implies a safe read and the 'oldest first' ordering is a genuine behavioral detail. However, it says nothing about return shape (names vs. paths), whether the list can be empty, 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?

A single front-loaded sentence with zero filler; the ordering detail is attached directly to the resource rather than buried.

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

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

For a zero-parameter tool with no output schema, the description should at least indicate what a returned snapshot looks like so the agent can hand an identifier to htb_hosts_restore. It covers purpose and ordering but leaves the return-value contract unspecified.

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. The description correctly implies no filtering or sorting options are needed to call it.

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

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

States a specific verb ('List') and resource ('/etc/hosts snapshots'), plus the ordering ('oldest first'), which cleanly separates it from the mutating siblings htb_hosts_backup and htb_hosts_restore. It never names a sibling explicitly, 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 listing purpose implies the workflow (inspect snapshots before htb_hosts_restore), but the description gives no explicit when-to-use, prerequisites, or named alternative. Usage is inferred rather than stated.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It identifies an update to the managed block but does not say whether removal is idempotent, what happens if the host is absent, whether the change is reversible, whether a backup is created, or what permissions are required.

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

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

A single front-loaded sentence that states action, target, scope, and selector format with 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 single-parameter tool with a complete schema, the definition is minimally adequate. However, as a mutation tool with no annotations or output schema, it should at least state idempotency, missing-host behavior, and relationship to backup/restore siblings.

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

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

Schema coverage is 100%, and the single parameter is documented with 'Hostname or IP to remove'. The description repeats that the selector accepts a hostname or IP but adds no matching/format details beyond the schema, 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?

The description states a specific verb (Remove) and resource (HTB host entry), and scopes it to the managed block by hostname or IP. This clearly separates it from siblings like htb_hosts_add or htb_hosts_show, though it does not explicitly name alternatives.

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 versus htb_hosts_clean or htb_hosts_add, nor any prerequisites or exclusions. Usage is only implied by the mutation verb 'Remove'.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'Restore' implies overwriting the current /etc/hosts and the default-to-latest behavior is disclosed, but it never says the existing file content is replaced, whether a pre-restore backup is taken, or what privileges are required.

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

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

A single sentence that front-loads the verb and resource and packs the default-behavior rule into a parenthetical. Nothing is wasted and nothing needs to be scanned for.

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-optional-parameter tool with no output schema, this covers the core action, but with zero annotations the omission of destructiveness (current hosts file is discarded), error behavior for unmatched names, and multi-match handling leaves meaningful 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 coverage is 100%, so 'Backup name or substring' is already documented. The description adds real value by explaining the omission default (most recent snapshot), which the schema does not state for this optional 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?

Specific verb (restore) plus resource (/etc/hosts) plus source (a snapshot), which cleanly separates it from siblings like htb_hosts_backup and htb_hosts_list_backups. It stops short of naming those siblings as the related steps, but the operation itself 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 parenthetical 'most recent if no name is given' tells the agent what happens when the parameter is omitted, which is genuine usage guidance. However, there is no statement of prerequisites, no mention that a backup must exist first, and no pointer to htb_hosts_list_backups for discovering names.

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

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

With no annotations, the description carries the full burden. It usefully discloses the blast radius ('every entry') and that tags are overwritten rather than merged, which is the key risk. It does not say whether manually curated tags are lost, whether the change is reversible, or whether it requires a populated host 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?

A single front-loaded sentence with the action first and the motivating case in parentheses. Zero filler, nothing to trim.

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-parameter tool with no output schema this is close to sufficient, but a bulk mutation with zero annotations and no reversibility warning leaves an agent guessing about side effects. A hint about backing up first (a sibling exists for exactly that) or about failure when a box name is missing would close 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies the operation is global and requires no scoping arguments.

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

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

States a specific verb and resource: 'Recompute every entry's tag from its box name', which is clearly distinct from siblings like htb_hosts_add, htb_hosts_clean and htb_hosts_restore. It doesn't name an adjacent sibling (e.g. htb_hosts_clean) to sharpen the boundary, so it stops short of a 5.

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

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

'fixes bulk tag=imported' implies the triggering scenario, so an agent can infer when this tool is warranted. However, there are no explicit when-not conditions, no mention of prerequisites (e.g. that host entries must already exist), and no pointer to alternatives such as htb_hosts_backup before a bulk overwrite.

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

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

With no annotations, the description carries the full load and does disclose key traits: read-style lookup, return of bare values only (not formatted output), and the non-obvious fact that multiple patterns NARROW rather than widen. It omits error/empty-match behavior and result ordering.

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 sentences, each earning its place, with the core action and output shape front-loaded before the matching semantics and the use case.

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-param, 100%-covered, annotation-free read tool with no output schema, this covers purpose, output shape, and the tricky matching semantics. Only the `index` parameter's effect on results and empty-result behavior go unaddressed.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning the schema lacks: that `patterns` matches against ip/tag/hostname and that multiple patterns are conjunctive, plus that `field` defaults to 'ip'. The `index` parameter is left 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?

Names a specific verb and resource ('look up managed entries ... return just their bare values') and states the output shape, which implicitly distinguishes it from the sibling htb_hosts_show. It never names that contrast explicitly, so an agent must infer it, which keeps it short of a 5.

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

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

Gives a concrete use case ('resolve a box name to its IP before scanning') plus the AND-narrowing rule. It offers no explicit when-not guidance or named alternative among htb_hosts_show / htb_hosts_list-style siblings.

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

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

With no annotations, the description carries the full burden and does disclose the main return structure and the effect of full=true. It does not explicitly state that the tool is read-only, nor does it cover permissions, side effects, or pagination behavior.

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

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

The description is short, front-loaded with the main return shape, and then explains the two parameters in context. Every sentence adds useful information without repetition.

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 and no annotations, so the description should ideally explain the returned structure more fully. It identifies top-level entries/groups and the full=true inclusion behavior, but it does not describe the fields within those structures or other relevant output details.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds useful meaning: `patterns` narrows the selected entries exactly as htb_hosts_select does, and full=true includes unmanaged/system entries such as localhost. It clarifies that pattern filtering applies to entries rather than groups.

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 resource and result shape: a structured overview of managed hosts, with both flat entries and grouped-by-box groups. It is clear what the tool returns, but it does not explicitly distinguish its purpose from siblings such as htb_hosts_select or htb_hosts_list_backups.

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 through 'overview', the `patterns` narrowing behavior, and the `full=true` option for unmanaged/system entries. However, it does not explicitly say when to use this tool instead of htb_hosts_select or other sibling tools.

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