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

The description highlights that the authentication bearer never leaves the CLI, which is a security-related behavioral trait. It also states the return format as {status, headers, body} or error envelope. However, it does not disclose other behavioral aspects like rate limits, request timeouts, or idempotency semantics that might be relevant for a generic API request 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?

The description is brief at two sentences, with the core action stated first. Every piece of information serves a purpose, and there is no fluff or repetition. It efficiently conveys the essential elements.

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

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

Given the tool has five parameters and no output schema, the description provides a reasonable overview: it specifies the API target, authentication, and return shape. However, it lacks details about potential errors, parameter constraints (e.g., path format, allowed body types), and usage context within the servonaut.dev ecosystem. The return format description partially compensates for the missing output schema.

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?

All five parameters are described in the schema with their descriptions, so the schema coverage is 100%. The tool description does not add additional meaning to the parameters beyond saying it's an 'authenticated request'. For example, it doesn't elaborate on how the 'path' relates to endpoints or how 'body' should be structured. The return format description is helpful but not directly about 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?

The description clearly states the action ('Make an authenticated request'), the target ('servonaut.dev REST API'), and the authentication method. It also specifies the return format, providing a clear understanding of the tool's function. This distinguishes it well from sibling tools like 'aws_call' or 'get_server_info'.

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 provides no explicit guidance on when to use this tool versus alternatives from the sibling list. It does not mention scenarios where this tool is preferred or when to use other tools that might target different APIs. This leaves the agent without context for appropriate invocation.

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

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

With no annotations, the description carries the full burden and does well: it declares read-only behavior, names the data sources (auth.log/secure tail with journald ssh units as fallback), and lists two specific error codes. It stops short of stating permission requirements or volume/rate limits, but the behavioral profile is substantially 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?

Three tightly packed sentences: purpose and scope first, then data source and read-only status, then return shape and errors. No filler and the most important information is front-loaded.

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

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

There is no output schema, but the description inlines the full JSON return shape for all three sections and enumerates the error codes, so an agent knows both inputs (via schema) and outputs. Nothing material is missing for a 3-parameter summary 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 schema already documents top_n, instance_id, and since_minutes with defaults and ranges. The description adds no parameter-level detail (e.g. it never mentions top_n or since_minutes), 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 (Summarize) and resource (SSH auth activity on one instance), and enumerates the exact content categories (failed logins, invalid-user probes, accepted logins). This distinguishes it cleanly from siblings like journal_errors, docker_log_summary, and security_audit.

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 scope ('SSH auth activity on one instance') implies when the tool applies, but there is no explicit guidance on when to choose it over alternatives such as journal_errors or security_audit, nor any stated prerequisites. Usage is inferable rather than directed.

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

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

With no annotations, the description carries the full behavioral burden and does so well: reads auto-paginate and run read-only; mutation requires mutate=true plus dangerous guard mode; destructive verbs are refused unless enabled in config and even then require a two-phase token confirm where the first call does not touch AWS; region/account pin the call. This is exactly the safety, reversibility, and execution-flow detail an agent needs.

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

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

Front-loaded with the core purpose and boundary before the safety rules, and nearly every clause earns its place (pagination, mutation gating, two-phase confirm, pinning). It is a dense single block that would read better split into bullets, but it is not padded.

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

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

For an 8-parameter, nested, no-output-schema generic passthrough, the description covers the operational essentials: scope, pagination, mutation/destructive safety, and region/account pinning. It does not describe the shape of the returned boto3 response, which is a minor gap for a generic passthrough.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters and the baseline is 3. The description reinforces the operation naming convention and params PascalCase format, and adds a little on region/account pinning, but does not mention max_items and adds little beyond the schema.

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

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

States a specific mechanism (boto3 passthrough), a clear scope (the AWS read surface), and enumerates the operation patterns it covers (Describe*/Get*/List*/Filter*/Lookup*) with concrete examples. It draws an explicit boundary against pre-wrapped siblings ('that isn't pre-wrapped'), so an agent can tell it apart from aws_list_regions, s3_list_buckets, etc. 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?

Explains when to reach for it (operations not already pre-wrapped, with example method names) and when mutating/destructive paths apply (mutate=true, dangerous guard mode, two-phase confirm). It implies the pre-wrapped siblings should be preferred for common ops but does not name a specific sibling to route to, so it falls short of explicit when-not guidance.

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

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

With no annotations, the description carries the full burden and does well: it discloses sort order (newest-first), filter semantics (case-sensitive glob), the default owner scope, and the rationale for the 50-result cap (bounding describe API consumption). It stops short of stating read-only nature explicitly or any error/auth behavior, but the behavioral context is substantial.

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 front-loaded and the constraints following. 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?

Covers purpose, filtering, defaults, and result bounding, which is enough to call the tool correctly. Without an output schema it doesn't describe the returned AMI fields, but for a straightforward list tool the description is nearly 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?

Schema description coverage is 100%, so the schema already documents all five parameters. The description reinforces defaults (amazon, case-sensitive glob, 50 cap) but adds little beyond what the schema 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 ('List AMIs in the given region') with scope (region-bound) and ordering (newest-first). The resource is unique among the aws_list_* siblings, so an agent can disambiguate it, though it doesn't explicitly name any alternative 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?

Provides default behavior (amazon-owned) and filter semantics but gives no explicit when-to-use guidance or exclusions relative to siblings like aws_list_instance_types or aws_call. Usage is implied rather than stated.

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

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

No annotations are provided, so the description carries the full behavioral burden. "List" implies a read-only operation and the description hints at return content (vCPU/RAM sizing), but it says nothing about pagination relative to max_results, whether results are cached or truncated, or auth/account scoping behavior. Adequate but with clear gaps.

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 with zero waste. The purpose is front-loaded and the downstream-usage hint follows immediately, making it scannable in a large tool list.

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 step in to name the returned attributes (vCPU and RAM sizing), and it ties the tool to aws_run_instances, which is the main reason an agent would call it. It omits pagination/truncation behavior for max_results and any note that instance types may be region-limited, keeping it just shy of fully complete.

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

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

Schema description coverage is 100%, so region, account, and max_results are already fully documented in the schema. The description adds the framing that region scopes the listing and that sizing data is returned, but no syntax, format, or default behavior beyond what the schema states. Baseline 3 is 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 ("List EC2 instance types"), scopes it to "the given region," and names the payload fields returned (vCPU and RAM sizing), so the agent knows what it gets back. It also links itself to the downstream tool aws_run_instances, which helps distinguish it from the many other aws_list_* siblings, though it does not explicitly differentiate itself from aws_list_amis or aws_list_regions.

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 to drive aws_run_instances input" gives an explicit when-to-use condition and names the downstream consumer, which is the key decision point for an agent picking a size. There are no exclusions or negative guidance (e.g., when to prefer a cached list or another source), so it falls short of 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses region scoping and the intended chaining use, but says nothing about read-only nature, permission/account requirements beyond the schema's 'account' field, or the shape of returned data.

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 core action stated first and the chaining hint second. Nothing needs 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 simple two-parameter read tool with no output schema, the description covers purpose and the key downstream use. It is a bit thin on behavioral details (permissions, return contents), which is the only 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%, so both parameters are already documented in the schema. The description adds no syntax or format detail for 'region' or 'account' beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('List EC2 key pairs') and scopes it to the given region. The resource is distinctive enough to separate it from sibling listing tools, but the description never explicitly contrasts itself with alternatives like aws_list_amis or aws_run_instances.

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 tells the agent when to use the result: feed key_name values into aws_run_instances. It gives a clear forward path but offers no when-not-to-use conditions or comparison to other key/credential-related tools.

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

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

With no annotations, the description must carry the behavioral burden, and it discloses the genuinely non-obvious trait that the list call is global and the region parameter does not scope the result. It stops short of describing return format or any auth/permission requirements, so it is helpful but not fully transparent.

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

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

Three tight sentences with the core purpose front-loaded and no filler; each sentence adds distinct information (what it lists, how bootstrap_region is used, and its default).

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 two-parameter list tool with no output schema and no annotations, the description covers purpose and the key parameter behavior adequately. It could note the return shape or permissions, but nothing essential is missing for correct 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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining that bootstrap_region only bootstraps the EC2 client and does not affect the global call. That clarifies the parameter's real effect, which the schema text alone does not convey.

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

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

The description states a specific verb (List) and resource (AWS regions) and scopes it to those 'enabled on the account', so the operation is unambiguous. It does not explicitly reference a sibling, but no other sibling tool lists regions, so disambiguation is effectively achieved by the name and phrasing.

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 clarifies a usage-critical point -- that bootstrap_region only affects client construction and the call itself is global -- which helps an agent invoke it correctly. However, it gives no explicit when-to-use/when-not guidance or alternatives among the many aws_* siblings, so usage is only implied.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'List' implies a safe read, and it does disclose how the output feeds aws_run_instances, but it says nothing about pagination, permissions required, or result shape. Partial disclosure against a full burden yields a 3.

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 and followed by the actionable integration hint. Every sentence earns its place with zero 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 two-parameter read-only list tool with no output schema, the description covers purpose, scope, and how to use the result, which is nearly all an agent needs. It omits only return/pagination details, a minor gap for a simple list 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 coverage is 100%, so both region and account are already documented in the schema. The description only restates the region scoping ('in the given region') and adds no semantics for the optional account parameter, giving no value beyond the schema. Baseline 3 is correct.

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

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

States a specific verb+resource+scope: 'List EC2 security groups in the given region.' The resource (security groups) is distinct from other aws_list_* siblings (amis, subnets, regions), so the agent can distinguish it without opening schemas. It stops short of explicit sibling differentiation, which keeps it at 4.

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 concrete downstream guidance: use the returned group_id values as entries in security_group_ids passed to aws_run_instances. This tells the agent why and when to call it (as a discovery step before launching instances). No when-not-to-use or exclusion conditions are given.

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. "List" does imply a safe, non-destructive read, and the chaining hint tells the agent what the output contains, but there is no mention of permissions, pagination, or throttling behavior for a multi-result AWS listing call.

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. The purpose is front-loaded and the second sentence is a distinct, actionable workflow instruction rather than padding.

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

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

For a simple two-parameter list tool with no output schema, the description covers purpose, scope, and the handoff to aws_run_instances. It does not state the return shape or ordering, though the chaining hint implicitly reveals that subnet_id values are present in the output.

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% for both parameters, so the schema already documents region and account. The description restates region's role but adds no meaning beyond what the schema provides, and never mentions the account 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 (List) and resource (VPC subnets) scoped to a region. The resource is unambiguously distinct from sibling aws_list_* tools (amis, regions, key pairs, security groups), so an agent can select it 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?

Adds concrete downstream routing: use the returned subnet_id values as the subnet_id argument to aws_run_instances. That is genuine when-to-use guidance, but there is no when-not or mention of the other subnet-consuming 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?

With no annotations, the description carries the full burden and does disclose meaningful behavior: it is a 'brief OS-level restart' and 'billing continues,' which tells the agent the instance stays up and costs are unaffected, unlike stop/terminate. It omits disruption details (downtime, in-flight connection loss) and any permission requirements, keeping it short of a 5.

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

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

Three compact clauses, front-loaded with the operation, followed by effect and safety instruction. Every clause earns its place with 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 simple single-instance mutation with no annotations and no output schema, the description covers what it does, its side effects, and the confirmation requirement. It would be complete at 5 if it mentioned that the instance must be in a running state (implied by 'running') or noted any permission/return expectations.

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 region, account, and instance_id (including the '<account>/<id or name>' form) are already fully documented in the schema. The description adds no parameter-level meaning beyond that, 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 (Reboot) and resource (a running AWS EC2 instance), which cleanly separates it from the sibling mutation tools aws_stop_instance, aws_start_instance, and aws_terminate_instance. An agent can identify the operation 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?

The description gives one actionable precondition, 'Confirm with the user before calling,' which is real usage guidance. However, it never says when to choose reboot over stop/start (e.g. to clear a hung process without losing the instance) or any exclusions, so the routing guidance is only implied.

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

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

With no annotations, the description carries the behavioural burden and discloses critical traits: immediate billing, cost, dangerous guard mode, required user confirmation, and that it returns JSON with new instance IDs. It omits permissions requirements, failure modes, and resource persistence implications, keeping it below a 5.

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

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

The description is front-loaded and tightly structured: purpose first, then the cost warning, guard-mode restriction, confirmation procedure, and return format. Every sentence adds distinct decision-relevant information with no waste.

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, dangerous mutation tool with nine parameters and no annotations or output schema, the description covers the key decision points: cost, guard mode, confirmation, and return shape. It is missing details about IAM permissions and partial-failure behaviour, but is otherwise sufficient.

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

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

Schema description coverage is 100%, so the schema already defines all nine parameters. The description names a subset (AMI, instance type, region, count) but adds no syntax or meaning beyond what the schema provides, matching the baseline of 3 when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: 'Launch one or more new AWS EC2 instances.' The word 'new' distinguishes it from sibling aws_start_instance, which starts existing stopped instances, so an agent can tell them apart without opening schemas.

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

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

It gives clear usage context: 'Reserved for dangerous guard mode' and requires summarising parameters and confirming with the user before calling. It does not explicitly name alternatives such as aws_start_instance for existing instances, so it falls short of full when/when-not guidance.

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 a real side effect most would miss: 'resumes billing while the instance is running.' The user-confirmation requirement is also a meaningful behavioral constraint. It omits auth/permission requirements and any error or state-transition behavior, so it falls short of 5.

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

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

Two sentences, zero waste, and well front-loaded: action first, then requirements, then the cautionary note. Every sentence earns its place.

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

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

For an annotation-free mutation tool with no output schema, the description surfaces the two things an agent most needs — required inputs and the billing consequence plus confirmation gate. It does not address return behavior or failure modes, a minor gap given there is no output schema to lean on.

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

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

Schema description coverage is 100%, so the schema already documents instance_id, region, and the optional account label in full detail. The description adds nothing about parameter formats or the account-qualified '<account>/<id>' syntax. 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?

Precise verb+resource: 'Start a stopped AWS EC2 instance.' It is immediately distinguishable from the sibling mutators aws_stop_instance, aws_reboot_instance, and aws_terminate_instance 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?

Gives a clear calling context ('Start a stopped instance') plus an explicit prerequisite ('Requires both the instance ID and the region') and a procedural gate ('Confirm with the user before calling'). It does not name alternatives (e.g. aws_stop_instance) or state when-not-to-use, so it stops short of the top tier.

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 delivers: EBS-backed/restartable semantics, that disk state is preserved, that EBS billing continues while instance-hours pause, and that user confirmation is required. These are exactly the side effects an agent must know before invoking a mutating call.

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 action, then consequences, then the confirmation requirement. No filler and every clause carries operational meaning.

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 annotations and no output schema, the description covers the safety-critical behavior well. It stops short of stating required IAM permissions or how to confirm the resulting state, which would round it out.

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

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

Schema description coverage is 100%, so instance_id, region, and account are already documented in the schema, including the '<account>/<id or name>' addressing form. The description adds no parameter-level meaning beyond that, 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 (Stop) and resource (AWS EC2 instance) with a scope qualifier (EBS-backed; restartable). It is immediately distinguishable from the siblings aws_start_instance, aws_reboot_instance, and aws_terminate_instance because it explicitly frames the operation as reversible.

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 clear operating context — this causes an outage until the instance is restarted, and the agent should confirm with the user first. The contrast with termination is implicit via 'restartable' and 'disk state preserved', but no alternative tool is named and no exclusion is stated outright.

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

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

With no annotations, the description carries the full behavioral burden and does so admirably: it discloses irreversibility, instance-store data loss, EBS volume detachment/destruction governed by DeleteOnTermination, and a guard-mode restriction. This is exactly the safety context an agent needs before a destructive call.

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

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

Front-loads the destructive nature ('PERMANENTLY terminate'), then data-loss mechanics, then the confirmation instruction. Every clause earns its place with 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 destructive 3-parameter tool with no annotations and no output schema, the description covers the critical gaps: irreversibility, data-loss consequences, guard-mode gating, and mandatory human confirmation. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents instance_id, region, and account including the '<account>/<id or name>' syntax. The description only references instance ID and region in the confirmation instruction and adds no new parameter semantics. Baseline 3 is 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 (terminate) and resource (AWS EC2 instance) and immediately disambiguates from the sibling stop/reboot tools with 'PERMANENTLY' and 'Irreversible'. An agent can distinguish this from aws_stop_instance and aws_reboot_instance 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?

Gives clear usage context ('Reserved for dangerous guard mode') and an explicit pre-call requirement to confirm with the user, including what to state (instance ID, region, data-loss implications). It does not explicitly name aws_stop_instance as the non-destructive alternative, but the destructive framing largely implies it.

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

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

With no annotations, the description carries the full behavioral burden. It discloses layer selection logic, fallback behavior, reversibility, and a danger warning, and notes it will recommend rather than silently edit the firewall. It omits auth/permission requirements and exact side effects on existing rules, but is otherwise rich.

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

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

Front-loaded with the core action, followed by precision on layer resolution and a safety flag. Every sentence earns its place; no redundancy or 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 dangerous mutation tool with no output schema and no annotations, the description covers purpose, behavior, and safety adequately. It could go further on what unblock does or how existing rules are affected, but an agent has enough to select and invoke 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 100%, so baseline is 3. The description adds meaning beyond the schema by explaining how the 'site' parameter resolves across layers (WebACL preference, SG/NACL fallback, host-layer recommendation), enriching understanding of a key 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 (block/unblock) and resource (IP/CIDR) and explains its unique layer-resolution behavior, which distinguishes it from simple firewall edits. The phrase 'at the layer that actually works' and the fallback logic make its scope clear 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?

It implies when to use it (blocking/unblocking an IP) and includes a critical safety warning ('DANGEROUS — confirm with the user first'), but it never names or contrasts with alternatives like the sibling ip_ban_set or waf_rate_rule_set. Usage is implied rather than explicitly guided.

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

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

With no annotations, the description carries the full burden and does well: it discloses the SSH-based probing side effect, the local-cache write, and the full set of count=0 reason codes (opt_out | disabled | no_modules_matched | all_probers_failed) plus remediation for the SSH auth case. It stops short of stating idempotency/overwrite behavior, cost, or expected duration, which keeps it from a 5.

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

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

Front-loaded with purpose and trigger, then return shape and failure semantics in descending order of importance. Dense and mostly waste-free, though the long parenthetical reason-code list and the final remediation sentence make it longer than strictly necessary.

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 the description compensates fully by enumerating the returned fields (instance_id, count, successes, failures) and the conditional 'reason' code. For a two-parameter build tool this covers everything an agent needs to invoke it and interpret 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by enumerating what the probed modules actually are ('OS, runtimes, services, web stack, logs, etc.') and confirming the omit-to-probe-all default. It adds real value to the 'modules' parameter rather than restating 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 and resource ('Build memory from scratch for a managed instance') and immediately distinguishes scope: it probes all enabled modules over SSH and writes to the local cache. An agent can separate this from get_server_memory and refresh_server_memory 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 trigger condition ('Call this when get_server_memory returns code="missing"') and the alternative motivation ('when you want a fresh full scan'), which routes the agent between the sibling memory tools. Nothing is left to inference.

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

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

With no annotations, the description carries the behavioral burden; it does disclose the returned data (state, IPs, region, type), which is useful. But it omits whether this is read-only, what permissions are required, and whether it works only for managed instances vs custom servers.

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 waste; the parenthetical efficiently enumerates return fields. It is appropriately sized for a one-parameter read 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?

There is no output schema, and the description partially compensates by listing the return fields. But with no annotations and many similar-sounding siblings, an agent lacks the routing and safety context needed to call 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 100% and the single instance_id parameter is fully documented in the schema, including the account/name and custom/name formats. The description adds nothing beyond the schema, so 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?

Clear verb+resource ("check status") plus the returned fields (state, IPs, region, type), so an agent knows what it gets. However, it does not differentiate from siblings like list_instances, get_server_info, or relay_status, which sound closely related.

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 context or alternatives are given. The phrase "any managed instance" hints at scope but there is no guidance on when to prefer this over list_instances or get_server_info.

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, so the description carries the full burden. It does add genuinely useful behavior — filters are exact, case-sensitive matches and may be combined — which is not in the schema. However it omits read-only confirmation, result volume/pagination behavior, and any auth/permission notes, leaving gaps for a tool with zero annotation coverage.

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

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

Two compact sentences that front-load the verb and resource, then the filter semantics and use case. Every clause carries information; nothing is padded, though it could be marginally tighter.

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 or annotations, so the description must stand alone; it covers purpose, filter semantics, and a use case. The main remaining gap is the return shape and read-only nature, but for a filtered-lookup tool with 100% schema coverage on parameters this is largely 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?

Schema coverage is 100%, so the baseline is 3, but the description earns above baseline by adding semantics the schema lacks: the filter params (event_name, username, resource_type) are exact, case-sensitive, and combinable. It adds no extra meaning for region/account/hours_back/max_results, which the schema already documents.

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

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

States a specific verb+resource: 'Look up AWS CloudTrail management events'. The resource (CloudTrail) is clearly distinct from the sibling CloudWatch log tools, so an agent can route without opening the schema. It stops short of explicitly contrasting with any 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?

Offers an implied use case ('useful for auditing who changed what, and from which source IP') but gives no when-to-use vs when-not guidance and never names an alternative (e.g. cloudwatch_get_log_events). The agent must infer that CloudTrail is the right source for audit trails.

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

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

With no annotations, the description carries the behavioral burden, and it does disclose that aggregation is server-side, that group_by trades raw lines for a ranked summary, and that summary_only returns a count. It omits read-only framing, throttling/limits, and return format, but adds genuine behavioral context beyond the schema.

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

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

Three tight sentences, front-loaded with the core action, then the aggregation mode, then the count-only mode. No filler; every clause conveys callable behavior.

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 10-parameter tool with no output schema and no annotations, the description covers the main sources of complexity (group_by mode, summary_only, filter behavior) so an agent can call it correctly. Minor gaps remain on ranking/return-shape expectations, but the annotation-free safety profile is implicitly read-only.

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 reinforces group_by, top_n default, and summary_only but adds little semantic detail (e.g., no ranking semantics) beyond what the schema 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?

States a specific verb and resource ('Fetch recent events from a CloudWatch log group') and further distinguishes its three modes (raw lines, server-side ranked summary, count-only). An agent can tell this apart from cloudwatch_list_log_groups or get_logs 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 clear conditional guidance: set group_by to get a ranked summary 'instead of raw lines — avoids dumping huge log pulls,' and summary_only for just a count. It explains when to pick each mode but names no sibling alternative and gives no explicit when-not.

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

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

No annotations are provided, so the description carries the full behavioral burden. It implies a read-only query but never states that it is non-destructive, does not mention that Insights queries bill per GB scanned and can be slow, and says nothing about result-return behavior or failure modes. For a cost-bearing AWS query tool the behavioral disclosure is thin.

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 no filler. The core action and its scope come first, then the differentiation from the sibling and the required inputs. Every clause 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 annotations and no output schema across 8 parameters, the description is adequate but not complete: it does not explain that the returned columns depend entirely on the query, says nothing about the query window defaults/timeouts, and omits cost implications. Minimum viable for a query tool, but an agent would benefit from 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 description coverage is 100%, so every parameter is already documented in the schema. The description's 'provide a query plus log_group or log_groups' restates the mutual exclusivity already implied by the schema fields, adding no syntax, valid-value, or trade-off detail beyond it. 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+resource: run a CloudWatch Logs Insights query over one or more log groups. It goes further by naming the sibling cloudwatch_top_ips and clarifying that this is the general-purpose aggregation primitive, so an agent can distinguish the two without opening either schema.

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

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

Explicitly routes the agent with 'use it when cloudwatch_top_ips doesn't compute what you need,' and enumerates the kind of aggregations it fits (top IPs, status mix, URI ranking, time-bucketing). No explicit when-not beyond that single named alternative, and no mention of cost/size limits that would steer an agent away for very expensive scans.

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

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

With no annotations, the description carries the full behavioral burden. It discloses that the tool is a listing operation and what it returns (stored bytes and retention per group), but does not state authentication requirements, explicit read-only status, or pagination limits. This is minimum viable for a read-only list tool.

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

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

Two concise sentences, front-loaded with the core action. 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 simple list tool with a fully documented schema and no output schema, the description provides the necessary purpose and return-value context. It omits usage guidance and behavioral details, but those are handled by other dimensions.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's mention of the prefix filter restates what the schema already documents and adds no new parameter semantics.

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

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

The description states a specific verb and resource ('List AWS CloudWatch log groups') plus an optional filter condition. It does not explicitly differentiate from sibling CloudWatch tools (e.g., cloudwatch_get_log_events), 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 or alternative selection criteria. The only contextual detail is the optional prefix filter, which is parameter information rather than usage direction.

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

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

With no annotations, the description carries the full behavioral burden. It discloses that it parses WAF/ALB structured logs and what it counts, and it is implicitly read-only, but it does not state AWS permission/auth requirements, scan cost, or rate behavior — and the 50000-event cap is only surfaced in the schema, not the description.

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, verb-first and front-loaded, with the analytical output and the operational use case packed in without any 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?

No output schema exists, and the description only partly covers the return shape (per-IP total/allowed/blocked). For a 7-parameter AWS tool with no annotations, missing auth/permission and output-format detail leaves it adequate but not fully self-sufficient.

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 seven parameters (limit, region, account, log_group, hours_back, max_events, action_filter) are already documented in the schema. The description adds no parameter-level detail (e.g. expected log format, region defaults), 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 ('Rank') and resource ('top client IPs in a CloudWatch log group'), and adds what it parses (WAF/ALB structured logs) and the output metrics (total, allowed, blocked per IP). It does not name a sibling, but the domain is specific enough that an agent can distinguish it from cloudwatch_get_log_events or cloudwatch_insights.

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 use context: 'use it to find abusive IPs before banning,' which points toward the ban/block workflow. However, it never states when NOT to use it or names alternatives (e.g. cloudwatch_insights for ad-hoc queries), so it stops short of explicit routing.

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

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

With no annotations, the description carries the full burden and does so: it declares the operation read-only, states the auth requirement (db_profile plus password from the secret store), and contrasts the summarised default with the raw per-session dump so the agent knows the cost/verbosity of each mode.

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, front-loaded with the purpose, then the default behavior, then the override and prerequisite. Every clause carries information; nothing is padded or restated.

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 tool with no annotations and no output schema, the description compensates well by enumerating what the summary returns (saturation, sessions grouped by command/state with counts and oldest age, and the 10 longest-running queries). Auth and mode requirements are all present, leaving no obvious gap an agent would need.

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

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

Schema description coverage is 100%, so the schema already documents instance_id, app and full. The description reinforces the default-vs-full distinction but adds no syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Show an instance's DB connection saturation + a session summary') and explicitly scopes what the default output contains versus the raw dump. It is clear what the tool does, but it never distinguishes itself from the overlapping sibling db_top_queries, which also surfaces slow queries.

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

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

Gives explicit mode guidance: default summarises the server-side view, and 'Pass full=true for the raw SHOW FULL PROCESSLIST / pg_stat_activity dump'. It also flags the prerequisite ('Requires a db_profile for the instance'). It stops short of saying when to prefer this over db_top_queries or other DB diagnostics.

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 full burden. It discloses that the tool is mutating (destructive) and affects both db_profile and secret. It does not detail error handling or idempotency, but the main behavioral traits are well communicated.

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: the first explains purpose and relationship, the second gives a usage warning. Every word adds value, no fluff. The structure is clear and front-loaded.

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

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

Given the tool's simplicity (3 parameters, no output schema), the description covers the main aspects: what it does, its relation to a sibling, and a safety guideline. It does not explain return values or edge cases, but for a removal tool with a clear undo role, this is adequate. A minor addition about what happens if the instance doesn't exist could improve completeness.

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 parameters are already documented. The description adds context by framing the tool as the undo operation, which helps interpret the parameters (especially delete_secret). However, it does not provide per-parameter details beyond the schema, so the added value is moderate.

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 clearly states the verb 'Remove', the resource 'db_profile and its stored DB secret', and explicitly names the sibling tool 'db_setup_save' as the undo operation. This distinguishes it from other tools in the sibling list and makes the purpose 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 says 'the undo for db_setup_save' which tells when to use it. It also adds 'Mutating: confirm with the user first' as a guideline for safe use. It doesn't explicitly describe when not to use, but the sibling context makes the scope clear. A small gap is the lack of alternative tool references for non-undo scenarios.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses that the operation is mutating, requires user confirmation, writes to two stores (secret store + db_profile), and that the password is read server-side by token and never enters the agent's context. It omits idempotency/repeat-commit behavior and whether an existing profile is overwritten.

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 action and outcome before the safety note. Every clause earns its place; 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 9-parameter, mutating tool with no annotations and no output schema, the description covers purpose, prerequisites, credential-handling security, and the confirmation requirement. Minor gaps remain around failure behavior (e.g., expired token, unreachable DB) and repeat invocations.

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% across all 9 parameters, so the baseline is 3. The description reinforces the token's provenance ('Staging token from db_setup_scan') and the side effects of the instance/label defaults, but adds no syntax or format detail the schema does not already carry.

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

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

States a specific verb+resource pair ('Commit a staged DB credential ... to the secret store and write a db_profile') and explicitly names the source tool (db_setup_scan) and the downstream consumers (db_processlist / db_top_queries). An agent can distinguish this from db_setup_remove and db_setup_scan 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?

Establishes the prerequisite chain clearly: the credential must come from db_setup_scan, and it warns 'Mutating: confirm with the user first.' It does not name db_setup_remove as the inverse/alternative or state when a re-scan is required, so it stops just short of full when/when-not guidance.

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

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

No annotations are provided, so the description carries the full burden — and it delivers: read-only reads over SSH, redacted previews with a staging token, and the password held server-side and never returned to context. This discloses the security/auth model an agent needs before invoking a credential-discovery 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 and efficient overall, but 'read-only' is stated twice ('READS the app config READ-ONLY' and the trailing 'Read-only.'), which is mild 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?

With no annotations and no output schema, the description compensates by describing what is returned (redacted previews + staging token) and the security model. It is largely self-sufficient, though return-value detail could be marginally richer.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema, which sets the baseline at 3. The description's mention of sources and web roots roughly mirrors the source/search_path params without adding format or syntax detail beyond the schema.

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

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

States a specific verb and resource ('Discover an instance's DB credentials') plus the credential sources (.env / DATABASE_URL / wp-config.php / docker env), and routes to the sibling db_setup_save. An agent can distinguish it from setup-adjacent siblings 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 clear workflow context ('to set up the db tools with no manual config') and an explicit next step ('Then call db_setup_save with the chosen token'). It does not state when NOT to use it or contrast against db_setup_remove, so it falls short of the full when/when-not/alternatives bar.

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

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

With no annotations, the description carries the full burden and does well: it declares the operation read-only, discloses the engine-specific instrumentation used, and flags the Postgres extension prerequisite plus the db_profile/secret-store auth requirement. It omits any statement about return size, cost, or whether the profiling itself is heavy on a production instance.

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?

Short and front-loaded, with the core purpose in the first clause and prerequisites after. The telegraphic fragments ('For the shared-RDS noisy-neighbour case.') are efficient but slightly cryptic in isolation.

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 or annotations exist, so the description must set expectations, and it does cover the data source, read-only nature, and setup requirements. It leaves the returned shape and the interaction between db_profile and instance_id unaddressed, but nothing critical to correct invocation 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% and all three parameters are documented there, so the baseline is 3. The description adds a genuine extra: it reveals a required 'db_profile' concept that is not in the schema at all, which is useful context but also leaves the relationship between db_profile and instance_id unexplained.

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

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

States a specific verb and resource ('Show the slowest / heaviest queries for an instance's DB') and even names the underlying per-engine data sources, which tells an agent exactly what it will get. It does not, however, contrast itself against the close sibling db_processlist, so an agent must infer the difference between 'top queries by resource' and 'currently running queries'.

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 usage context ('For the shared-RDS noisy-neighbour case') and prerequisites ('Requires a db_profile; password from your secret store', pg_stat_statements must be enabled). It stops short of naming an explicit alternative tool for the single-DB case, which keeps it out of 5 territory.

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 provided, the description carries the full behavioral burden and does so well: it declares the tool is read-only and lists the underlying boto3 services, notes that it returns partial results when IAM scope is incomplete, and discloses the optional SSH-based remote-IP trust check. It does not discuss rate limits or detailed auth requirements beyond IAM scope, but the disclosed operational traits are 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?

The description is front-loaded with the core purpose and discovery chain, then adds diagnostic questions, failure behavior, and read-only context in tight succession. Every clause adds useful information, and there is 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 complex, multi-service discovery tool with no output schema and no annotations, the description is unusually complete: it covers purpose, scope, diagnostic use cases, read-only safety, IAM-related partial-result behavior, and the SSH-based remote-IP check. The 100% schema coverage handles parameter details, so nothing critical is missing for correct 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 100%, so the schema already documents region, verbose, instance_id, and check_remoteip. The description adds only a high-level hint about forwarded client IP trust, which maps to check_remoteip but does not add syntax or meaning beyond what the schema provides. Baseline 3 is 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?

The description names a specific verb and resource ('Map an AWS instance's ingress path') and enumerates the full discovery chain (instance → target groups → load balancers → listeners/rules → WebACL → IP sets + rate rules). It also distinguishes the tool from siblings by stating the exact questions it answers, so an agent can tell what it does 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?

It gives clear context by naming the diagnostic questions it answers ('behind ALB or direct?', 'which WebACL fronts it?', 'is the WAF even attached?'). However, it does not explicitly say when to prefer this over siblings such as aws_call, waf_rate_rule_set, or web_traffic_summary, so it stops short of full when/when-not/alternatives guidance.

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 delivers: read-only guarantee, exact collection mechanics (df bytes+inodes, pseudo-filesystems excluded, depth-2 du), the sudo -n fallback, and the error case df_not_available. This is unusually rich behavioral disclosure for a diagnostic tool.

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

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

Three dense sentences with the primary scope front-loaded, then mechanics, then return shape and errors. No filler; every clause carries information.

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

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

No output schema exists, yet the description inlines the exact return JSON (filesystems fields, fullest_mount, top_consumers) and enumerates the failure mode. For a two-parameter read-only tool this is fully complete.

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

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

Schema coverage is 100%, so both parameters (including the top_n default and range) are already documented in the schema. The description implies top-consumer behavior but adds no syntax or selection meaning beyond the structured fields.

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

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

States a specific verb+resource ('per-filesystem disk usage on one instance') and adds the secondary deliverable (top directory consumers under the fullest mount). It is clearly scoped to a single instance, distinguishing it from fleet-wide health tools. No sibling tool overlaps this disk resource.

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 strongly implied (disk-pressure investigation) but there is no explicit 'use this when…' statement, no exclusions, and no named alternative. The read-only nature guides intent somewhat, but the agent must infer when to reach for this versus get_server_memory or fleet_health_snapshot.

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 declares 'Read-only' and gives the exact return shape ({events: [{container, event, count, last_at}]}), which is real added value. However, it says nothing about permissions, cost/latency of aggregation, or whether counts are per-container or global, so the safety profile is disclosed but the operational behavior is thin.

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 scope-constrained action, followed by the read-only flag and return schema. Every sentence contributes and nothing is padding.

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

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

No output schema exists, but the description compensates by specifying the return JSON structure, and it flags read-only despite missing annotations. It is nearly complete for a simple two-parameter read tool; only the absence of instance-scoping caveats or event-filtering notes keeps it short of full.

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 (instance_id with account/name format, since_minutes with range and default) are fully documented in the schema. The description only echoes the lookback-window concept, adding no syntax or bounds beyond the schema, so baseline 3 is 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 (aggregate) plus a precisely scoped resource (container lifecycle events die/oom/restart/kill/start on one instance over a lookback window). The enumerated event types and 'one instance' scope clearly separate it from siblings like docker_logs, docker_log_summary, docker_stats, and docker_ps without needing to name them.

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 only implied: 'over a lookback window' and 'on one instance' suggest the diagnostic scenario, but there is no explicit when-to-use-this-vs-docker_log_summary or docker_stats guidance, and no stated exclusions. An agent must infer the routing decision.

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

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

With no annotations, the description carries the full burden and does well: it declares read-only, discloses both output streams (stdout+stderr), and notes results are bounded. It omits auth/permission requirements and error or truncation behavior, which keeps it below a 5.

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

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

Three short clauses with zero filler, and the core action plus scope is front-loaded before the safety and return-shape notes.

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 read-only tool with full schema coverage, the description covers purpose, safety, and the return shape ({container, lines}), so no output schema is needed. Only missing piece is guidance on sibling log tools.

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

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

Schema description coverage is 100%, so the schema already documents lines, container, and instance_id fully, making 3 the baseline. The description's 'bounded' wording loosely reinforces the lines limit but adds no syntax or format detail beyond the schema.

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

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

States a specific verb and resource ('Tail one container's logs') with scoping qualifiers (stdout+stderr, bounded) that separate it from generic log tools like get_logs and aggregate ones like docker_log_summary. It never names an alternative 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?

There is no statement of when to choose this over get_logs, docker_log_summary, or cloudwatch_get_log_events, all of which are log-retrieval siblings. The 'one container' framing implies the scope but provides no explicit selection criteria 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?

With no annotations, the description carries the full burden and does well: it declares 'Read-only', discloses that aggregation is client-side and raw logs never leave the operator, and enumerates the failure modes (docker_not_available, docker_permission_denied, container_not_found, no_logs_available). It stops short of describing rate limits or scan cost.

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 aggregation purpose, followed by mode behavior, privacy note, result shape and errors. Dense but each clause carries distinct value; not padded.

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

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

No output schema exists, yet the description spells out the returned JSON fields (kind, status_mix, error_rate_4xx/5xx, top_paths, error_patterns, lines_scanned) and the named error set, so an agent knows both what it gets and how it fails.

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 instance_id, container, top_n and since_minutes are already documented with ranges and defaults. The description adds no constraint meaning beyond that, 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 (aggregate) and resource (one container's log stream) and immediately signals its distinction from a raw-log sibling by naming the two summarization modes. An agent can tell this apart from docker_logs without opening a schema.

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

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

The description explains the internal conditions under which it switches parsing modes, which is useful behavior context, but never states when to choose this over docker_logs or docker_events_summary. Usage is implied rather than routed.

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

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

With no annotations, the description carries the full burden and does so: it declares read-only behavior, discloses the underlying mechanism (docker inspect over SSH, sudo -n fallback), and names concrete error modes (docker_not_available, docker_permission_denied). This is unusually complete behavioral disclosure.

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: purpose and fields first, execution/safety model second, return shape and errors last. No redundancy with the schema.

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

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

No output schema exists, yet the description specifies the exact JSON return shape and the error identifiers, so an agent knows both what it gets back and what failures to expect. Nothing material for correct invocation 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 coverage is 100% and the single instance_id parameter is fully documented in the schema, including the '<account>/<name>' and 'custom/<name>' forms. The description adds only the scoping constraint ('one instance'), so the baseline 3 is 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+resource ('List Docker containers') with scope ('on one instance') and enumerates the returned fields, making it clearly distinguishable from siblings like docker_stats, docker_logs, and docker_events_summary.

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 'on one instance' phrasing implies this is a per-instance inventory call and the field list hints at the use case, but it never states when to prefer this over docker_stats, service_state, or fleet_health_snapshot. Usage is implied rather than explicit.

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

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

No annotations are provided, so the description carries the full burden. It discloses the read-only safety profile, the single-sample (non-streaming) behavior, and the exact JSON return shape. It does not cover auth/permission requirements or error behavior, but for a read-only stats tool the transparency is solid.

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 core purpose and metrics, followed by the return shape. Every clause earns its place with 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 simple read-only tool with one fully documented parameter, the description supplies purpose, scope, safety, and return structure. No output schema exists, but the description provides the JSON shape, leaving nothing critical 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?

There is one parameter with 100% schema description coverage, and the schema already documents instance_id formats. The description adds no additional parameter semantics, so the baseline 3 is 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 resource and scope: 'single-sample resource usage for every running container on one instance' with the exact metrics returned (CPU %, memory used/limit, memory %, PID count). This clearly separates it from host-level get_server_memory and listing docker_ps, though no sibling is named explicitly.

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

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

The 'single-sample' framing implies a point-in-time snapshot use case, but there is no explicit when-to-use, when-not, or named alternative such as docker_ps for listing or get_server_memory for host memory. Usage must be inferred from the purpose statement.

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?

Discloses read-only behavior, external API dependencies (ip-api.com free, AbuseIPDB key required), and implied network calls. Without annotations, this is good transparency.

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 cover all key points: purpose, blocking strategy, and data source requirements. No fluff, front-loaded with core functionality.

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 enrichment tool with no output schema, the description provides sufficient context: what data is returned, how to use it, and dependencies. Minor gap: no mention of output structure or error handling.

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 input schema covers the 'ips' parameter with 100% description. The tool description adds value by explaining what enrichment entails (reverse DNS, ASN/org, country, score) and how results guide blocking, beyond schema details.

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?

Description clearly states the tool enriches IPs with reverse DNS, ASN/org, country, and AbuseIPDB score. It also explains the purpose: deciding blocking strategies (single IP vs. entire ASN/org). This is specific and informative.

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 guidance on how enrichment informs blocking decisions (single /32 vs. wholesale block of bulletproof host). It mentions read-only nature and prerequisite for AbuseIPDB key. However, it does not explicitly compare to sibling tools like block_ip or ip_ban_set.

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 reasonably well: it asserts 'Read-only', discloses the fan-out nature (implicitly many hosts, slow, timeout-governed), and documents failure behavior ('Unreachable hosts are listed separately'). It omits auth/credential requirements and any cost or rate-limit caveat for large fleets.

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, front-loaded with the action and output shape, with no filler. The 'Surfaces the sick box...' sentence is justification rather than instruction, which slightly dilutes density but still earns its place as rationale for the fan-out design.

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 usefully previews the return shape (one table; load, CPU count, memory %, php-fpm pool saturation, listening web stack; unreachable hosts separated), which is what an agent needs to interpret results. It leaves the exact column format and large-fleet latency unstated.

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 all four parameters are self-documenting (region filter, account, timeout range, running_only default), so the baseline is 3. The description adds no parameter-level meaning beyond what the schema already supplies.

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+resource+scope: 'Triage the whole fleet in one table via SSH fan-out' plus an enumerated set of returned columns. It is clearly distinguishable from single-host siblings like get_server_info, check_status, and get_server_memory, and it also states the mechanism (SSH fan-out).

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 usage context ('Triage the whole fleet', 'surfaces the sick box without SSH'ing into each by hand'), which tells the agent this is the bulk, first-pass diagnostic rather than a per-host deep dive. It stops short of explicitly naming alternatives (get_server_memory, run_command) or exclusions, so it is not 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?

No annotations are provided, so the description carries the full behavioral burden, yet it discloses almost nothing: no read-only/mutation signal, no permission or auth requirements, no note on truncation, size limits, or behavior when log_path does not exist. The word 'Get' weakly implies a read, but that is inference rather than disclosure.

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, and the core action is front-loaded. It is appropriately sized, though the brevity comes partly from under-specification rather than discipline.

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 is the only place to learn return shape or failure behavior, and it says nothing about either. For a log-retrieval tool sitting among several similar siblings, it should at minimum indicate output format (raw lines) and what happens on missing files or permission errors.

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 (instance_id, log_path, lines) are already documented in the schema, including the '<account>/<name>' and 'custom/<name>' conventions. The description adds no syntax, format, or default behavior beyond what the schema already 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 ('Get log file content') and scopes it to 'any managed instance', so the operation is unambiguous. However, it draws no distinction from sibling log tools such as docker_logs, journal_errors, auth_log_summary, or cloudwatch_get_log_events, leaving the agent to guess which log source applies.

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 prefer this tool over the many sibling log-fetching tools, nor any prerequisites or exclusions. An agent seeing docker_logs and cloudwatch_get_log_events side by side has nothing to route on.

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

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

No annotations are provided, so the description carries the full behavioral burden. It implies a read-only lookup but never says so, nor does it mention permissions, whether the instance must be reachable, or rate limits. For a cross-instance query tool this is a meaningful gap.

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

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

One tight sentence with the returned fields front-loaded after the verb. No filler, though the parenthetical field list is doing double duty as scope clarification.

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 usefully lists the returned fields (hostname, uptime, disk, memory), and the single required parameter is fully covered by the schema. It lacks any note on failure modes or instance-state prerequisites, keeping it short of 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?

Schema description coverage is 100%, so the single instance_id parameter and its '<account>/<name>' / 'custom/<name>' formats are already fully documented in the schema. The description adds nothing beyond the schema, 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?

States a specific verb (Get) and resource (server info) and enumerates the fields returned (hostname, uptime, disk, memory), which helps distinguish it from narrower siblings like get_server_memory or disk_usage. It does not explicitly name which sibling to prefer, 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 the many overlapping siblings (check_status, get_server_memory, disk_usage, fleet_health_snapshot). The phrase 'from any managed instance' hints at scope but gives no exclusions or 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?

With no annotations, the description carries the full burden and does so: it discloses the error contract (code='missing'), the redaction behavior of raw_output (config.memory.redaction_enabled default true), and the structured field set returned for format='full'. This is far beyond 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?

Front-loaded with the critical 'call FIRST' guidance, which is the right structure. The format enumeration is long and slightly dense, but nearly every clause maps to a distinct decision an agent must make, so little 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?

No output schema exists, yet the description fully characterizes the return content per format (Markdown digest, raw JSON modules, drop-in context block, compact stack profile) plus failure handling. An agent has everything needed to call 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 coverage is 100%, but the description goes well beyond the schema's terse 'Output format (default: summary).' by explaining what each of the five enum values produces and when to pick each — genuine added semantics.

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 ('Return cached memory ... for a managed instance') and enumerates the covered domains (OS, runtimes, services, web stack, logs). It clearly distinguishes itself from build_server_memory and refresh_server_memory by being the read/cached accessor.

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 instructs 'Call FIRST before issuing SSH commands' and gives the exact failure path: on error code='missing', call build_server_memory(instance_id) then retry. It also conditions format choice on intent (detector recon, model context, full data).

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 largely meets it: it discloses that the tool mutates live traffic rules, that it returns an applied/failed split, and that user confirmation is advised. It stops short of stating required permissions or whether existing rules are overwritten.

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 doing work, with the accepted-input modes front-loaded and the confirmation warning placed last where it is most salient. Dense but not padded.

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

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

For an 8-parameter mutation tool with no annotations and no output schema, the description covers the target resolution, the bulk/single duality, and the return shape (applied/failed). Only permission requirements and reversibility of an unban are left unstated.

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 real meaning beyond the schema: it clarifies that cidr is an alias, that 'site' resolves the WebACL actually fronting the box, and that config_name and site are alternative paths. That relationship logic is not obvious from the field list alone.

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 pair (ban/unban) and resource (IPs/CIDRs) plus the three targeting mechanisms (named config, site's WebACL, bulk list). It is unambiguous, but it does not distinguish itself from the sibling tool 'block_ip', which appears to cover overlapping ground.

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 explains the input modes (single ip_address, bulk ip_addresses[], or a resolving 'site') and warns 'confirm with the user first', which implies the mutation context. However, it never states when to pick this over 'block_ip' or 'waf_rate_rule_set', so sibling routing is left to inference.

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

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

With no annotations, the description carries the full burden and does so well: it declares read-only behavior, the transport (journalctl over SSH with a sudo -n fallback), and enumerates the two error conditions (journal_not_available, journal_permission_denied). It omits rate limits, timeout behavior, and what happens when no problems are found, so it falls just short of exhaustive.

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 aggregation scope, followed by the read-only/transport caveat, then the return shape and errors. The inline JSON return skeleton is dense but justified given there is no output schema. Every sentence carries information, with only minor density cost.

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 read-only diagnostic tool with no output schema and no annotations, the description supplies everything needed: the aggregation facets, the access mechanism and fallback, the exact return structure per section, and the failure modes. Nothing required for correct invocation is missing.

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

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

Schema description coverage is 100%, so instance_id, top_n, and since_minutes are already fully documented in the schema. The description adds no parameter-level detail (e.g., how since_minutes interacts with the 'CURRENT failed units' section) beyond what the schema states, making the baseline 3 correct.

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

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

States a specific verb (aggregate) and a specific resource (journald problems on one instance), then enumerates the exact facets: error-priority entries per unit, OOM kills, restart/failure records, and current failed units. This clearly separates it from siblings like get_logs, docker_logs, auth_log_summary, and service_state without needing to name them.

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 scope statement ('journald problems on one instance') gives clear context for when this tool applies versus generic log or service-state tools. However, it names no explicit alternative and gives no when-not-to-use guidance, leaving the agent to infer routing.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that results span every configured account and multiple providers and explains the '<account>/<name>' naming convention, but says nothing about return format, pagination, or volume for accounts with many servers.

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

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

Three tight sentences with the core scope front-loaded and no filler. The final sentence on the '<account>/<name>' form is dense but earns its place by enabling precise targeting.

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-only, no-argument list tool with 100% schema coverage and no output schema, the description covers scope, providers, optional filters and the multi-account addressing scheme. Only return format/pagination is unaddressed, which is minor here.

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

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

Schema coverage is 100%, so the schema already documents the three filter parameters; the description mostly restates them ('filter by region, state or account'). It does add the meaningful naming-convention hint for targeting a single server, but the parameters themselves gain little beyond the schema.

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

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

The description states a specific verb (List) and resource (managed server instances) and clarifies scope: every configured account across AWS EC2, OVH, Hetzner and custom servers. It implicitly distinguishes itself from the provider-specific aws_* siblings by being the cross-provider fleet lister, but it never names a competing tool to make that routing explicit.

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 says results can be filtered by region, state or account, which implies when the filters are useful, but gives no when-to-use/when-not guidance and does not point to alternatives (e.g. get_server_info for a single host). 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?

No annotations are provided, so the description must inform about behavior. It only states the basic action and the stale_only filter, omitting details like authorization, rate limits, pagination, or output format.

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

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

The description is two sentences, each earning its place. The main purpose is front-loaded, and the filtering option is explained concisely.

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 list tool with one optional boolean parameter and no output schema, the description adequately explains functionality. It could be improved by mentioning return format or likely fields, but it is mostly 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?

Schema coverage is 100% for the single boolean parameter. The description adds clarification on what 'stale' means (exceeded TTL), but the schema description already covers the parameter's purpose. Baseline 3 is 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?

The description clearly states the tool lists all instances with cached server memory, and optionally filters for stale ones. It is a specific verb+resource combination and distinguishes from sibling tools like get_server_memory.

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 implicitly says when to use (to list cached instances, optionally with stale_only), but provides no guidance on when not to use or alternatives among the many sibling tools.

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 description discloses that the tool wraps the call in a JSON-RPC 2.0 envelope and returns the raw response, which is useful. However, it does not state whether the operation is read-only or destructive, or any authentication or rate limit considerations.

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 extremely concise at two sentences and 26 words. It is front-loaded with the core action and provides immediate clarity without unnecessary 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 simple wrapper tool with only two parameters and no output schema, the description provides sufficient context: what it does, the envelope, and the return format. It could mention error handling, but overall it is complete enough.

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 parameters are well-described in the schema. The description adds context that the arguments are wrapped into a JSON-RPC call, but this is not essential for understanding parameter 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 clearly states the specific action: invoking a tool on the hosted MCP server. It uses a specific verb 'invoke' and identifies the resource (the MCP server at mcp.servonaut.dev). This distinguishes it from sibling tools that have more specialized purposes.

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 is provided on when to use this generic tool versus the many specialized sibling tools. An agent could benefit from knowing that this tool is for calling MCP tools that are not already exposed as dedicated functions.

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

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

With no annotations, the description carries the full burden and does so: it declares read-only behavior, explains the underlying mechanism (apt-get simulation, dnf updateinfo/check-update), and explicitly states 'never installs' so the agent knows no mutation occurs. It also names the exact error condition (pkg_manager_not_supported).

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

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

Front-loads the purpose, then compresses platform mechanics, return shape, and error into a tight set of clauses. Every sentence adds information with 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?

Despite having no output schema and no annotations, the description documents the return JSON structure, the read-only guarantee, platform coverage, and the failure mode. An agent has everything needed to call and interpret 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 100% and the single instance_id parameter is fully documented in the schema, including the '<account>/<name>' and 'custom/<name>' formats. The description adds no parameter detail beyond that, 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 resource and scope: 'Pending package updates on one instance' with the exact data returned (security vs total counts, reboot-required, sample packages). No sibling tool covers package updates, so it is unambiguously distinguishable from the fleet/log/aws-family tools listed.

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 scope ('on one instance') and the platform note imply when it applies (checking patch state before maintenance), but there is no explicit when-to-use vs. an alternative tool, nor any stated prerequisite beyond the instance id. Usage is implied rather than directed.

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

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

With no annotations, the description carries the full burden, and it does disclose the read-only nature and the CloudWatch data source plus the metric set returned. However, it omits auth/region requirements and any pagination or failure behavior an agent might need before invoking.

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

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

Three tight sentences with the purpose and metric list front-loaded and no filler. The noisy-neighbour framing and read-only note both earn their place, though the metric enumeration is somewhat list-heavy.

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-only metric-snapshot tool with no output schema and no annotations, the description covers the source, the operation, the returned metrics, and the primary use case. It is nearly complete, missing only return format and required permissions.

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

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

Schema description coverage is 100%, so the schema already documents region, account, db_instance, and window_hours. The description only restates db_instance as the DB instance identifier, adding no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb (Snapshot) and resource (an RDS instance's health from CloudWatch) and enumerates the exact metrics returned. It is clearly differentiated from query-oriented siblings like db_processlist and db_top_queries, though it doesn't name any sibling explicitly.

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

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

It gives one strong usage cue — 'the first check for the shared-RDS noisy-neighbour case' — which tells the agent when to reach for it. But there is no guidance on when to use alternatives (e.g., db_top_queries or db_processlist) or any prerequisites, leaving usage only partially specified.

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

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

With no annotations, the description carries the full burden and does well: it discloses the return content (titles AND bodies), the default ordering (newest-first), the active-findings default, and a substantive trust model ('agent-authored and unverified ... re-verify before taking any destructive action'). It omits pagination and auth/rate-limit context, keeping it from a 5.

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

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

Front-loaded with purpose, then mode behavior, then the trust caveat. Every sentence earns its place and the safety-critical warning is given prominent placement.

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

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

For a no-annotation, no-output-schema tool, the description covers return content, ordering, defaults, and the trust model adequately. Minor gaps remain around pagination and whether superseded findings appear by default, but the schema handles that flag.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including query, tags, limit, and include_superseded. The description largely restates the query semantics already present in the schema, adding only the 'active findings newest-first' framing, so baseline 3 is 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 (recall) and resource (previously-saved findings) and clarifies scope ('for an instance'). It distinguishes itself from the write counterpart remember_server_finding by noting it returns 'full titles AND bodies', though it never names list_server_memories, a sibling that could plausibly overlap.

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

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

Gives explicit mode selection: omit query to list all active findings newest-first, supply query for lexical search. This is clear actionable guidance, but it stops short of contrasting with siblings like list_server_memories or remember_server_finding.

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

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

With no annotations, the description carries the full burden, and it does disclose the key behavioral traits: it overwrites the cache (a destructive side effect), the probes run identically to build_server_memory, and the response is structured JSON with per-module successes/failures. It stops short of stating permission requirements or failure/partial-failure semantics.

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

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

Three tight sentences, front-loaded with the action and cache-overwrite semantics, then routing and return shape. 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?

Given no output schema, the description usefully sketches the return shape (structured JSON with per-module successes/failures) and fully covers equivalence and routing. Minor gaps remain around auth requirements and behavior on partial module failure.

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

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

Schema description coverage is 100%, so the schema already documents both instance_id and modules (including the 'omit to refresh all' behavior), giving a baseline of 3. The description adds no parameter-level detail beyond that.

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

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

States a specific verb and resource ('Re-probe memory modules ... overwrite the cache') and immediately frames it against the sibling build_server_memory, so the agent can distinguish the two without opening either schema.

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

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

Gives an explicit selection rule: use refresh_server_memory when updating existing memory after a deploy/upgrade, build_server_memory when no memory exists yet. This is the when-to-use/when-to-use-alternative guidance at its 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?

With no annotations provided, the description carries full burden. It discloses the two-phase behavior: health check first, then conditional restart via SIGTERM and new process. Adequate for a simple tool.

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

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

Two sentences, front-loaded with the core purpose. Every part adds value, no 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?

Simple tool with one param and clear logic. No output schema, but the description implies the outcome (no-op vs restart). Missing details on error handling or return values, but acceptable given simplicity.

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 already has 100% coverage for the single parameter. The description adds context by explaining the effect of 'force=true' ('skip the health-check'), integrating it into the usage flow.

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 uses a specific verb ('Heal') and resource ('stale Mercure relay connection'), clearly distinguishing it from sibling tools like 'relay_status' which only checks status. It states exactly what the tool does: consult backend, conditionally restart.

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?

States when to use: heal a stale connection. Provides an alternative behavior via 'force' parameter. However, does not explicitly contrast with 'relay_status' or mention when not to use this tool.

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

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

No annotations are provided, so the description carries full behavioral burden. It discloses that the tool reports data from servonaut.dev about the local CLI's relay connection, with specific output fields. This indicates a read-only, lightweight operation. However, it does not mention error conditions, permissions, or any side effects.

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 sentence, front-loaded with the action (report) and the specific outputs. Every word is necessary, with no fluff 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?

Given the absence of output schema and annotations, the description is quite complete for a simple status-checking tool. It explains the data source and what is returned. However, it does not mention whether the tool requires an active relay connection or authentication, but overall it provides adequate context.

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 input schema has zero parameters, so schema description coverage is 100%. The description does not need to add parameter information, and it does not. The baseline for zero-parameter tools is high, and the description adds value by specifying what the tool returns, which is sufficient.

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 clearly states the tool reports relay connection status from servonaut.dev, listing specific fields (connected flag, last heartbeat, client_ids). It distinguishes from sibling tools like 'relay_reconnect' (which is for reconnection) and 'check_status' (which is more general).

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