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 fully discloses behavior: it states read-only, identifies the log sources (auth.log/secure tail, journald ssh units as fallback), lists the exact return JSON structure, and enumerates possible errors (auth_log_not_available, auth_log_permission_denied). This goes far beyond a minimal 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?

The description is three sentences, each providing essential information: purpose, read-only/source fallback, return format and errors. It is front-loaded with the primary purpose and avoids repetition or fluff. Every word 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?

The tool has moderate complexity (multi-section JSON output, error handling, fallback sources) and no output schema. The description compensates fully by specifying the exact JSON structure and error names. Combined with schema descriptions, it gives an agent all necessary information to invoke and interpret results.

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

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

Schema description coverage is 100%, so the parameters (instance_id, top_n, since_minutes) are already well-documented. The description does not add extra meaning to the parameters; it focuses on output and behavior. Baseline 3 is appropriate as the schema carries the parameter explanation.

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 'Summarize SSH auth activity on one instance' with specific categories (failed logins, invalid-user probes, accepted logins) and grouping by source IP. This specific verb+resource combination distinguishes it from sibling log/audit tools like get_logs or 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 description provides clear context: it is a read-only summarizer for SSH auth activity on a single instance, with fallback sources mentioned. It does not explicitly name alternatives or exclusion cases, but the purpose is specific enough to imply when it should be used over raw log retrieval 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?

No annotations provided, so description carries full burden. It details auto-pagination for reads, read-only default, mutate flag, destructive guard mode with two-phase confirm, and region/account pinning. Very 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?

Single dense paragraph, front-loaded with purpose. Every sentence adds unique value. No fluff despite complex 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?

Covers all behavioral aspects (pagination, mutation, destruction safeguards, region/account). No output schema, but return values are implied. Complete for agent to use 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%, but description adds key context: snake_case operation names, PascalCase params keys, two-phase confirm flow, region/account pinning. Adds meaning beyond 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 clearly states it's a generic boto3 passthrough for specific AWS read operations (Describe*/Get*/List*/Filter*/Lookup*) and also covers mutating/destructive variants. It distinguishes from sibling tools which are pre-wrapped for specific AWS actions.

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 says when to use: for any non-wrapped read operations, and for mutating ops with mutate=true. Destructive ops require two-phase confirm and config. This gives clear guidelines on usage vs 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 full burden. It discloses sorting order, default owner, cap at 50, and case-sensitive glob filtering. It does not mention pagination or permissions, but for a read-only list tool, this is adequate.

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

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

Two sentences, front-loaded with main action and key details. No wasted words; every sentence adds value.

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

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

The description covers key behavioral aspects for a list tool with 4 parameters. It does not describe return structure, but no output schema exists. Given the simplicity, it is fairly 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 baseline is 3. The description adds context: sorting, glob behavior, cap justification, and default owner. This improves understanding beyond the schema's default descriptions.

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

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

The description clearly states the tool lists AMIs in a region, sorted newest-first, with filtering by partial name match and default owner. This distinguishes it from sibling tools like aws_list_regions or list_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?

The description sets expectations for usage (sorting, filtering, default owner, max cap) but does not explicitly state when to use this tool versus alternatives or when not to use it. However, the context is clear enough for an agent.

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 provided, but description clearly indicates read-only behavior and what data is returned (vCPU and RAM sizing). Could mention idempotency or pagination, but acceptable.

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

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

Two well-structured sentences with no wasted words. Front-loaded with purpose and followed by usage guidance.

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?

Tool has only two parameters and no output schema; description covers purpose, usage context, and key output characteristics. Slightly missing pagination note but overall adequate.

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% with both parameters described. Description adds context for output but does not enhance parameter semantics beyond 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?

Description clearly states the tool lists EC2 instance types in a region with vCPU and RAM sizing, and explicitly distinguishes its purpose as input for 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?

States 'Use to drive aws_run_instances input', providing clear context for when to use this tool. Does not explicitly list exclusions or alternatives but is sufficient.

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 implies a read-only operation by using 'List', but does not explicitly state behavioral traits like permissions, rate limits, or side effects. For a simple list operation, this is adequate but lacks extra context.

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

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

Two sentences, no wasted words. The first states the action, the second provides valuable usage context. Every sentence earns its place.

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

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

For a simple one-parameter list tool, the description is fairly complete. It explains purpose, region, and output usage. No output schema exists, but for a list tool, the return format is implicit. Minor gap: no mention of error conditions or edge cases, but overall 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 coverage is 100% with one parameter 'region' described. The description does not add additional meaning beyond the schema, merely restating 'in the given region'. Baseline 3 applies as schema already documents the 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?

The description clearly states the tool lists EC2 key pairs in a given region, with a specific verb 'List' and resource 'EC2 key pairs'. It also explains the practical use of the returned key_name values, distinguishing it from other sibling tools like 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?

The description provides clear context for when to use the tool (to list key pairs) and explicitly ties the output to a related tool (aws_run_instances). It does not mention exclusions or alternatives, but none are necessary given the tool's specificity.

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 provided, but description discloses that the call is global and the region parameter is just for client construction. Adequate behavioral transparency for a read-only list.

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

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

Two sentences, front-loaded with purpose, no wasted words. Highly concise.

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

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

Given no output schema and simple single-parameter tool, description fully covers what the tool does and how the parameter behaves.

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 already describes the parameter, but description adds that the call itself is global, clarifying that the region doesn't scope results. Adds value beyond 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?

Clearly states it lists all AWS regions enabled on the account; specific verb and resource. No sibling tool duplicates this functionality.

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 that bootstrap_region is only used to construct the EC2 client and the call is global, giving clear context. No need for when-not-to-use as it's a simple listing.

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

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

No annotations provided, and the description only states the basic operation without disclosing behaviors like pagination, limits, or 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?

Two concise sentences, front-loaded with purpose and usage guidance. No unnecessary 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 one parameter and no output schema, the description is mostly complete. Missing minor details like default limits or pagination.

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 description adds little beyond the schema. The region parameter is adequately described in both.

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 it lists EC2 security groups in a given region, using specific verb and resource. It is distinct from other aws_list_* siblings.

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

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

Provides explicit guidance on using the returned group_id values for aws_run_instances, but does not mention when not to use or 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 full burden but only states it lists subnets. It lacks disclosure of any behavioral traits like authentication, rate limits, or read-only nature, which is minimal for an API 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 action and resource, 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 one parameter and no output schema, the description is complete. It tells what the tool does and how to use the result.

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

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

Schema coverage is 100% for the single parameter region. The description adds 'in the given region' which matches schema but doesn't provide extra semantics beyond what's already in the schema.

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

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

The description clearly states the tool lists VPC subnets in a region and provides a specific use case for the output, distinguishing it from sibling tools like 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?

It tells the agent to use subnet_id values for aws_run_instances, providing context for when to use this tool, though it doesn't explicitly mention when not to use it or 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 appropriately discloses that the reboot is brief, billing continues, and user confirmation is required, covering key behavioral aspects.

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 convey all essential information without unnecessary words, efficiently front-loading the purpose and critical usage note.

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

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

For a simple tool with two required parameters and no output schema, the description fully equips the agent with purpose, effect, and requirement for user confirmation.

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% with descriptions for both parameters. The tool description does not add additional meaning beyond what the schema provides, meeting the baseline.

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

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

The description clearly states the action ('Reboot'), the resource ('running AWS EC2 instance'), and key effects ('brief OS-level restart; billing continues'), distinguishing it from sibling tools like start/stop/terminate.

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 states 'Confirm with the user before calling,' providing a clear usage guideline. Though it does not explicitly compare to alternatives, the purpose is unambiguous.

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 full burden. It discloses 'Costs money — billing starts immediately' and 'Reserved for dangerous guard mode,' adding crucial behavioral context beyond the schema. It does not mention permissions or error handling, but is otherwise 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?

Four sentences, each earning its place: action, cost/danger, usage restriction, user confirmation instruction, return format. Front-loaded and no fluff.

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 high complexity of launching EC2 instances, the description covers cost, danger, user confirmation, and return format. Lacks mention of error handling or IAM permissions, but is fairly complete for a dangerous tool. Schema covers all parameters well.

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 references parameters to summarize (AMI, instance type, region, count) but adds no new semantics beyond what the schema already provides.

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 'Launch one or more new AWS EC2 instances,' providing a specific verb and resource. It distinguishes from siblings like aws_start_instance and aws_terminate_instance, which handle different lifecycle states.

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 instructs to 'Summarise AMI, instance type, region, count, and confirm with the user before calling,' and states 'Reserved for dangerous guard mode,' giving clear usage context. It does not explicitly mention alternatives, but the user confirmation directive is strong.

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 the billing impact and confirms the instance must be stopped prior to invocation. In the absence of annotations, this adequately describes behavioral traits.

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 verb and resource, with no unnecessary 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?

Given no output schema, the description covers the key context (billing, user confirmation, requirements). Missing return value details but sufficient for this simple action.

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

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

Schema coverage is 100% with parameter descriptions; the description restates the requirement for instance ID and region without adding additional semantic value 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 clearly states the action 'Start a stopped AWS EC2 instance' with the specific resource, distinguishing it from sibling tools like aws_stop_instance or aws_reboot_instance.

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 explicit guidance to confirm with the user due to billing implications, implying appropriate use cases. Does not contrast with alternatives but gives clear usage context.

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

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

With no annotations, the description carries full burden. It discloses all key effects: stops a running instance, preserves disk, restarts possible, EBS billing continues, instance-hours pause, and requires user confirmation due to outage. No contradictions.

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 three sentences, front-loaded with the main action, followed by essential details and a usage note. Every sentence adds value without redundancy. Highly efficient.

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 tool with no output schema, the description covers all needed information: purpose, effects, and a critical usage requirement (user confirmation). It is complete enough for an agent to select and invoke 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% with both parameters (region and instance_id) already described. The description adds no further parameter details beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool stops a running EC2 instance, specifying EBS-backed and restartable. It distinguishes from siblings like terminate (destructive) and start by noting disk preservation and billing continuation. The verb-plus-resource is precise.

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 includes an explicit directive to 'Confirm with the user' because of the outage. While it doesn't list alternatives or when-not-to-use, the behavioral note provides clear context. Given the sibling tools include start, reboot, and terminate, the description implies when to use stop vs. those.

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 key behaviors: irreversibility, instance-store data loss, EBS volume behavior per DeleteOnTermination flag, and required user confirmation. Annotations are absent, so description carries full burden and meets it well.

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?

Description is concise (3 sentences), front-loaded with the action, and includes essential details without unnecessary words. Every sentence adds value.

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

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

Given no output schema, the description adequately explains the destructive effects and data-loss implications. Could mention return status or confirmation in output, but overall sufficient for a dangerous mutation tool.

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

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

Schema coverage is 100% with basic descriptions for instance_id and region. The tool description does not add additional meaning beyond what is already in the schema, so baseline of 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 'PERMANENTLY terminate an AWS EC2 instance', specifying the verb (terminate), resource (EC2 instance), and permanence, distinguishing it from siblings like stop/reboot.

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?

Includes guidance: 'Reserved for dangerous guard mode' and 'ALWAYS confirm with the user (state the exact instance ID, region, and any data-loss implications) before calling.' Does not explicitly list when not to use or alternatives, but the caution is strong.

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 discloses the resolution logic (prefers WebACL, falls back to SG/NACL, recommends host layer), notes reversibility, and warns about danger. This provides good context, though it could mention required permissions or logging behavior.

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

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

The description is four sentences, front-loaded with the core purpose, and each sentence adds value. It is efficient and avoids redundancy, though a bullet list could improve readability slightly.

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 4 parameters and no output schema, the description covers the core functionality, resolution strategy, and safety warning. It is sufficiently complete for an IP blocking tool, though it does not describe the return format or confirmation behavior.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds context about how 'site' is resolved but does not add new semantics beyond what the schema already provides for parameters like 'ip' or 'region'. The action enum is already documented.

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

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

The description clearly states that the tool blocks or unblocks an IP/CIDR, and specifies that it resolves the best layer (WebACL, SG/NACL, or host). This verb+resource combination is distinct from sibling tools like 'ip_ban_set', making 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 explains when to use the tool (to block an IP at the appropriate layer) and includes a strong warning about danger and user confirmation. However, it does not explicitly state when not to use it or compare it to alternatives like '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?

No annotations are provided, so the description carries the full burden. It discloses that the tool probes over SSH, writes to local cache, and returns detailed success/failure JSON with reasons. It also explains common failure modes (SSH reachability/auth). However, it doesn't explicitly state that it overwrites the existing cache (implied by 'build from scratch'), nor does it mention required SSH permissions. Still, it is quite 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?

The description is moderately concise and well-structured: it starts with the primary action, then gives usage condition, then lists return fields, and finally explains failure handling. Each sentence serves a clear purpose. A slight reduction in length could improve conciseness, but it's effective.

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 complexity (SSH probing, multiple modules, caching) and absence of an output schema, the description covers the return format, failure reasons, and troubleshooting. It lacks details about error handling when the instance is invalid or unreachable beyond SSH issues, and doesn't specify timeout behavior. Still, it provides sufficient context for most use cases.

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 parameters well. The tool description does not add additional meaning beyond saying 'all enabled modules' (which matches schema). No extra usage hints or format details are provided, so the description adds minimal value over the schema. 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 builds memory from scratch by probing modules over SSH, which is a specific verb+resource combination. It explicitly distinguishes the tool from siblings like get_server_memory by specifying when to call it (when get_server_memory returns code='missing').

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 explicit usage guidance: 'Call this when get_server_memory returns code='missing', or when you want a fresh full scan.' This tells the agent exactly when to use this tool vs. alternatives, with a clear condition and purpose.

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 full behavioral disclosure burden. It implies a read operation ('Check status') but does not explicitly state it is read-only, non-destructive, or what side effects exist. Minimal behavioral context.

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

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

The description is a single sentence of 12 words, very concise and front-loaded with the verb 'Check status'. It wastes no words, but could potentially include a tiny bit more context without losing conciseness.

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

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

Given no output schema or annotations, the description covers the basic purpose and output fields. However, it lacks usage context, differentiation from siblings, and behavioral details. It is adequate but has clear gaps.

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

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

The input schema already has 100% coverage with a clear parameter description. The description adds no new parameter semantics beyond the schema, but it clarifies the output fields (state, IPs, region, type), which indirectly helps agents understand what they will get. Baseline score of 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 checks status of a managed instance and lists fields like state, IPs, region, type. However, it does not differentiate from sibling tool 'get_server_info', which likely returns similar information, so sibling differentiation is missing.

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 usage guidance is provided. There is no indication of when to use this tool versus alternatives like 'get_server_info' or 'list_instances'. No when-not-to-use or prerequisites are mentioned.

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

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

No annotations are provided, so the description carries the full burden for behavioral disclosure. It mentions 'management events' and optional filters but does not disclose limitations (e.g., event retention period, pagination, cost implications, or what happens if region is empty). The schema provides some details (default region behavior) but the description adds little beyond the basic action.

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 long, with the main action and key filters in the first sentence. Every word serves a purpose; no redundancy. It is efficient 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?

The tool has 6 optional parameters and no output schema. The description only hints at return fields (who changed what, source IP) but does not fully explain the return format, event structure, or how results are ordered. Without annotations, more detail is needed about behavioral aspects like default region handling and result limits.

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_description_coverage is 100%, so the baseline is 3. The description lists three filters (event_name, username, resource_type) which correspond to schema parameters, but adds no semantic value beyond the schema (e.g., does not explain how hours_back interacts with default or max_results limits). No extra context is provided.

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 'look up' and the specific resource 'AWS CloudTrail management events'. It lists key optional filters (event name, username, resource type) and describes the tool's purpose (auditing who changed what and from which source IP). This distinguishes it from sibling tools like aws_call or aws_run_instances which focus on different AWS services or actions.

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 usage context by stating it is 'useful for auditing who changed what', implying investigation scenarios. However, it does not explicitly guide when to use this tool versus alternatives (e.g., other audit tools like cloudwatch_get_log_events or aws_call). No exclusions or prerequisites are mentioned.

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

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

With no annotations, the description carries full burden. It discloses the dual behavior (raw events vs ranked summary), the performance hint of avoiding huge pulls, and the summary_only option. However, it does not mention read-only nature, cost, or rate limits. The time window (hours_back) is implied in 'last N hours'.

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 purpose. The second sentence is dense but packs the key modal distinction. Could be split for readability, but overall efficient without 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?

Given 9 parameters, no output schema, and no annotations, the description covers the main use cases but lacks detail on the return format (e.g., structure of raw events) and does not mention the max_events cap or the filter_pattern auto-quoting behavior. Adequate but not fully comprehensive.

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

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

With 100% schema coverage, baseline is 3. The description adds value by explaining that group_by produces a server-side ranked summary with default top_n=20, and that summary_only returns just the count. It also hints at the performance benefit. This goes beyond the schema's descriptions.

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

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

The description clearly states the tool fetches recent events from a CloudWatch log group, with optional filtering and an aggregation mode via group_by. It distinguishes itself from siblings like cloudwatch_top_ips (specific field) and cloudwatch_insights (analytics) by highlighting the raw vs ranked summary duality.

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

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

The description implies usage for fetching recent log events and offers a summary mode to avoid large pulls, but it does not explicitly state when to use this tool over alternatives like cloudwatch_insights or cloudwatch_top_ips. No when-not or explicit comparison to 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?

No annotations exist, so the description must fully disclose behavioral traits. It describes running a query but does not state whether the operation is read-only, what permissions are needed, or any rate limits or 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 three sentences long, front-loads the primary action, and contains no extraneous information. Every sentence adds value.

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

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

Given no annotations or output schema, the description fails to explain the return format, pagination, or behavioral aspects like read-only nature. It is incomplete for a tool with 7 parameters.

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 7 parameters are documented in the input schema (100% coverage), so the description adds minimal additional meaning beyond the schema. The mention of providing a query and log group/log groups is consistent with schema but does not enhance understanding.

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 it runs a CloudWatch Logs Insights query over log groups, and explicitly distinguishes itself from the sibling tool cloudwatch_top_ips by referring to itself as a general aggregation primitive.

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 explicitly tells when to use this tool ('when cloudwatch_top_ips doesn't compute what you need') and what to provide ('a query plus log_group or log_groups'), providing clear usage 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 provided, the description carries the full burden of behavioral disclosure. It only states that the tool lists log groups and shows stored bytes and retention, but does not mention that it is a read-only operation, potential costs, pagination behavior, or any other traits. The absence of such details leaves significant behavioral unknowns.

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, consisting of two sentences with no wasted words. It front-loads the core purpose and then provides an additional detail about what information is displayed. Every sentence serves a purpose.

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 simple nature of the tool (list with optional filter) and the absence of an output schema, the description adequately covers the key aspects: what it does and what information it returns. It does not mention pagination or that multiple groups may be listed, but for a list operation this is generally acceptable. The description is sufficient for understanding the tool's basic functionality.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds minimal semantic value beyond the schema: it reinforces that filtering is optional and that the region defaults to the boto3 default. However, the schema already provides this information ('Filter to log groups whose name starts with this prefix', 'defaults to the boto3 default region when empty'). The description does not significantly enrich understanding.

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 'List' and the resource 'AWS CloudWatch log groups', and specifies optional filtering by name prefix along with additional details shown (stored bytes and retention). This effectively distinguishes it from sibling tools like cloudwatch_get_log_events (which retrieves log events) and cloudwatch_top_ips (IP statistics).

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 indicates the tool is for listing log groups with an optional prefix filter, which implies its primary use case. However, it lacks explicit guidance on when to use it versus alternatives (e.g., cloudwatch_insights for querying log data), and does not mention when not to use it or any prerequisites. The usage context is implied but not fully clarified.

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 provided, so description carries full burden. It does not disclose important behavioral traits such as cost implications, rate limits, permissions needed, scanning limits (max_events cap only in schema), or behavior under heavy log volumes. Only mentions that it parses WAF/ALB structured logs, which is useful but insufficient.

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. First sentence states the core action and resource, second provides context and recommended use case. No fluff or repetition.

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

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

No output schema, but description partially describes output (total, allowed, blocked counts). Missing details like return format, ordering, error handling, and behavior when no matching logs. Adequate but not 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% with all 6 parameters described. The description adds no extra meaning beyond the schema; it does not elaborate on how parameters like action_filter or hours_back interact. Baseline score of 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?

Specific verb 'Rank' + resource 'top client IPs in a CloudWatch log group', and explicitly distinguishes from siblings like cloudwatch_get_log_events by mentioning parsing WAF/ALB logs to aggregate counts.

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 'use it to find abusive IPs before banning', providing clear usage context for abuse detection. Does not explicitly list when not to use, but the purpose is clear enough to differentiate from general log retrieval 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 provided, the description discloses read-only nature, default summary behavior, and what the summary includes (saturation, session counts, oldest age, top 10 queries). Also notes prerequisite of db_profile and password from secret store.

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?

Description is concise with three sentences that front-load the purpose, explain default behavior, and list requirements. No unnecessary words, though a bit more structure could improve readability.

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 adequately describes the summary output composition and mentions necessary prerequisites. Covers key aspects for a tool of moderate complexity.

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

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

Schema coverage is 100%, and the description adds context for 'full' (default vs raw) and 'app' (omitting for single-DB instances). This adds meaning beyond the parameter descriptions in the schema.

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

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

The description clearly states the tool shows DB connection saturation and a session summary, with specific detail on default summarized output versus raw dump via 'full=true'. It distinguishes from sibling 'db_top_queries' by focusing on overall process list rather than just top 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?

Clearly explains when to use default summary vs passing 'full=true' for raw dump. Mentions the requirement for a db_profile and password from secret store. However, does not explicitly mention when not to use or compare to alternatives like 'db_top_queries'.

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 full burden. It states mutating nature and server-side password handling, but does not disclose what gets destroyed (e.g., potential overwrite of existing profiles) or other 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?

Two sentences, front-loaded with core purpose and effect, followed by critical warning. Every sentence earns its place; no fluff.

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, and description does not specify return values (e.g., success message, error handling). With 9 parameters, it lacks detail on edge cases like overwrite behavior or error states.

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 description adds value: it clarifies that token is a staging token and password is never in context, and that label defaults to config-path derived value. This goes beyond parameter descriptions.

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

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

The description clearly states the tool's action: 'Commit a staged DB credential to the secret store and write a db_profile'. It specifies the verb 'Commit' and resource 'staged DB credential', and distinguishes from siblings like db_setup_scan and db_setup_remove.

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 explicit instructions: 'The password is read from server-side staging by token — never from your context' and 'Mutating: confirm with the user first'. It also implies when to use (to enable db_processlist/db_top_queries), but no explicit exclusions or 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?

Discloses read-only operation over SSH, redaction of previews, and that password is held server-side to prevent leakage. No annotation provided, so description carries the burden; it does well but could mention error handling.

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

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

Four sentences, no wasted words. Front-loaded with purpose, then behavior, then workflow, then safety note. Efficient and well-structured.

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

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

Explains return format (redacted previews + token) and workflow. No output schema, but description compensates. Could mention prerequisites like SSH access, but adequate for complexity.

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

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

Schema covers all parameters with descriptions (100% coverage). Description adds context like 'scan common web roots' for search_path but does not significantly deepen understanding beyond schema. Baseline 3 applies.

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

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

Clearly states verb 'Discover' and resource 'DB credentials', specifies sources (.env, DATABASE_URL, wp-config.php, docker env), and distinguishes from sibling db_setup_save which is the follow-up step.

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 mentions next step 'call db_setup_save with the chosen token' and indicates read-only nature. Does not explicitly list when not to use or compare with other tools, but context is clear.

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

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

With no annotations provided, the description carries full burden. It explicitly states the tool is read-only and details engine-specific data sources (MySQL: performance_schema, Postgres: pg_stat_statements). It also notes authentication requirements (db_profile, secret store password). No contradictions found.

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: four sentences that front-load the purpose, then cover engine-specifics, use case, and prerequisites. Every sentence adds essential information with no redundancy or fluff.

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

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

The description lacks details about the return format (e.g., what columns/fields the results contain) and does not mention error conditions (e.g., missing extension in Postgres). While it covers the primary use case well, these omissions reduce completeness for an agent needing to interpret results.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value beyond the schema by explaining the app parameter's matching behavior ('matched loosely against stored site labels') and reinforcing the limit's default range. The engine-specific context also helps interpret 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 tool shows 'the slowest / heaviest queries' for a database instance, mentioning specific engines (MySQL with performance_schema, Postgres with pg_stat_statements). It distinguishes itself from sibling tools like db_processlist by focusing on performance metrics rather than current processes, and even specifies the use case for shared-RDS noisy-neighbour scenarios.

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 clear context for when to use the tool: for an instance's DB to identify heavy queries, especially in a noisy-neighbour case. It mentions prerequisites (db_profile, password from secret store) and implies read-only access. It does not explicitly list when not to use it or alternatives, but the context is sufficient to guide an agent.

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 explicitly states the tool is read-only (boto3 elbv2/wafv2/ec2 Describe), warns that partial results may be returned with incomplete IAM scope, and discloses the default SSH behavior for check_remoteip. This is rich behavioral context beyond what the schema provides.

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 efficiently structured with no fluff. The first sentence states the core purpose and flow, the second answers the practical questions, the third notes failure behavior, and the fourth confirms read-only. Each sentence earns its place and is front-loaded with the primary purpose.

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 complexity (multi-hop AWS resource mapping), no output schema, and no annotations, the description is exceptionally complete. It explains the full scope, read-only nature, partial results under IAM restrictions, and parameter behavior (verbose/check_remoteip) sufficiently for an agent to invoke 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 the baseline is 3. The description does not add meaning beyond the schema for parameters; it mentions mod_remoteip/real_ip and verbose behavior, but these are already covered in the schema parameter descriptions. No additional semantic value is provided.

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 'Map' with a clear resource 'AWS instance's ingress path' and details the full chain (instance → target group → load balancer → listeners → WebACL → IP sets). It explicitly answers key questions like 'behind ALB or direct?' and distinguishes itself from sibling AWS tools by focusing on the complete ingress path.

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

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

The description implies when to use the tool by stating it answers specific ingress-path questions and notes that partial results are returned when IAM scope is incomplete. It lacks explicit exclusions or named alternatives, but the context is clear enough for an agent to select this tool over others when needing this particular mapping.

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 fully covers behavioral traits: it declares read-only operation ('Read-only'), details the underlying commands (df, du, sudo), excludes pseudo-filesystems, and mentions error conditions ('df_not_available'). The return format is also described, providing comprehensive 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?

The description is extremely concise: two sentences plus a brief metadata line. It front-loads the core purpose and includes all necessary details without any redundant language.

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 complexity, the absence of an output schema, and no annotations, the description provides complete context: inputs, behavior, return structure, and error handling. No gaps remain.

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 both parameters (instance_id, top_n) with descriptions, achieving 100% coverage. The description adds no new meaning beyond the schema, meeting the baseline of 3.

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's purpose: 'Per-filesystem disk usage on one instance plus the top directory consumers under the fullest mount.' It specifies the resource (disk usage on one instance) and the action (listing filesystems and top consumers), distinguishing it from sibling tools which cover different domains.

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

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

The description implies usage for checking disk usage but does not explicitly state when to use this tool versus alternatives or when not to use it. No exclusions or comparisons to sibling tools are provided, so the guidance is minimal.

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?

Declares 'Read-only' and provides return format, but no further behavioral details (e.g., rate limits, authentication). With no annotations, the description carries the burden, and it meets a basic level.

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

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

Two concise sentences, front-loaded with action and specifics. 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?

Provides enough context for a simple tool: explains events, return format, and parameter role. No output schema, but return structure is described. Could mention if there's pagination or limits.

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

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

Schema coverage is 100%, so baseline is 3. Description adds little beyond schema (e.g., 'lookback window' echoes since_minutes description). No extra meaning for instance_id.

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?

Clearly states it aggregates specific container lifecycle events (die/oom/restart/kill/start) on one instance over a lookback window, distinguishing it from sibling tools like docker_ps or docker_logs.

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?

Implies usage context (aggregating events on one instance) but does not explicitly state when not to use or mention alternatives. However, the sibling list and clear purpose make it relatively clear.

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

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

With no annotations, description carries full burden. It declares read-only, bounded, and return format. Missing details like authentication requirements or behavior on missing container, but overall sufficiently transparent for a simple tail operation.

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

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

Two concise sentences with key information front-loaded: operation, scope, safety, and output format. No unnecessary 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?

Given lack of output schema, description includes return format. Parameters well-covered by schema. Could mention error handling or follow behavior, but sufficient for a bounded tail tool.

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

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

Schema coverage is 100% so description adds minimal value beyond parameter names and types. The description's mention of 'tail' aligns with the lines parameter but doesn't provide new semantic context.

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 'Tail one container's logs (stdout+stderr, bounded)' with specific verb and resource. Distinguishes from siblings like docker_ps (lists containers) and cloudwatch_get_log_events (AWS logs).

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?

Description indicates 'Read-only' usage safety and 'bounded' nature, but does not explicitly compare to alternatives like cloudwatch_get_log_events or docker_log_summary, which would help guide tool selection.

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 explicitly states read-only behavior and that aggregation happens client-side without leaving logs. It also lists possible errors. However, it could mention authentication requirements or rate limits, but given the context, this is sufficiently 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?

The description is concise and well-structured. It front-loads the purpose, then provides parsing behavior, client-side note, output format, and error list without any redundant sentences.

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 complexity (conditional parsing, multiple output fields), the description is quite complete. It covers both modes, output keys, and errors. However, it lacks guidance on performance or limits (e.g., maximum lines scanned) and does not specify how the tool determines if logs look like access logs.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that 'top_n' applies to each section (top_paths and error_patterns) and by outlining the overall output structure, which helps understand how parameters affect results.

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 aggregates one container's log stream with specific parsing behaviors for access logs and error-pattern grouping. It distinguishes the tool from siblings like 'get_logs' or 'docker_logs' by focusing on summarization rather than raw log retrieval.

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

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

The description implies use when needing aggregated log summaries and describes internal conditional behavior, but it does not explicitly state when to use this tool versus alternatives like 'cloudwatch_get_log_events' or 'journal_errors'. No when-not or alternative tools are mentioned.

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

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

Discloses read-only nature, technical method (SSH docker inspect with sudo -n fallback), and lists two specific error types. With no annotations, the description carries full burden and reasonably covers behavioral traits for a 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 tightly packed sentences: first states function and output fields, second adds technical details and errors. No superfluous 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?

Describes return JSON structure with field names, error types, and read-only semantics. Lacks output schema, but the description compensates adequately. For a list tool with one parameter, coverage is high.

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 has 100% coverage with description 'Instance ID or name.' The tool description adds 'on one instance' but no new meaning beyond schema. 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?

Description clearly states 'List Docker containers' with specific fields returned (state, health, restart count, published ports, compose labels). Distinguishes from siblings like docker_events_summary (events), docker_logs (logs), docker_stats (stats) by listing its unique output fields.

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 explicit guidance on when to use this tool versus alternatives like docker_stats or docker_log_summary. Description implies single-instance use but doesn't provide criteria for selection among 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?

No annotations provided, but description declares read-only, single-sample nature, and return format. Adequately discloses behavior without omission.

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, no redundancy. Front-loaded with metrics and return type. Every word serves a purpose.

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 single parameter and no output schema, description covers purpose, metrics, return format, and read-only constraint. No gaps.

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

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

Schema already describes instance_id as 'Instance ID or name.' Description adds little beyond schema (coverage 100%), so baseline of 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?

Clearly states the tool retrieves single-sample resource usage (CPU, memory, PIDs) for all running containers on one instance. Distinguishes from siblings like docker_ps and docker_logs.

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 mentions it works on one instance and is read-only. While it doesn't contrast with alternatives, the context is clear enough for correct tool selection.

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?

No annotations provided, so the description carries the full burden. It declares the tool is read-only, uses SSH fan-out, and lists unreachable hosts separately. It does not detail error handling or performance implications, but the main behavioral traits are covered adequately.

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, efficient and front-loaded with the core purpose. Every word earns its place; no filler. Structured clearly with the main function first, then details.

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

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

Given the tool has 3 optional parameters and no output schema, the description provides sufficient context: what it does, how it works (SSH fan-out), what metrics it collects, and key behaviors (unreachable separate, read-only). An agent can decide to use it appropriately.

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

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

Schema coverage is 100%, so baseline is 3. The description adds no additional explanation for the parameters (region, timeout, running_only). The schema itself provides their descriptions, so no extra value from the description.

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's purpose: to triage the whole fleet via SSH fan-out, collecting specific metrics (load, CPU, memory, php-fpm, web stack). It distinguishes itself from sibling tools by focusing on fleet-wide health, contrasting with individual instance tools like get_server_info. The verb 'triage' and 'surfaces the sick box' are precise.

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

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

The description implies when to use it: for fleet-wide health without manual SSH. It mentions unreachable hosts are listed separately, giving context. However, it does not explicitly state when not to use it or name alternative sibling tools (e.g., list_instances, 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?

With no annotations, the description carries full burden for behavioral disclosure. It states 'Get' but does not explicitly indicate read-only nature, permission requirements, error behavior, or side effects. Minimal transparency beyond the verb.

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

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

The description is one sentence with no wasted words. It is front-loaded with the action and resource. However, it could incorporate more context without significant expansion.

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 3 parameters and no output schema or annotations, the description is too sparse. It omits important context like return format, error handling, and pagination behavior, making it incomplete for safe and accurate tool 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 baseline is 3. The description adds no extra meaning beyond the schema; it does not clarify parameter relationships or provide examples.

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 ('Get') and resource ('log file content from any managed instance'). It clearly indicates the tool's functionality, distinguishing it from sibling tools that target CloudWatch or Docker logs.

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 tool versus alternatives like cloudwatch_get_log_events or docker_logs. The description does not specify context, prerequisites, 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?

Without annotations, the description describes a read-only operation, which is correct. However, it fails to disclose potential behavioral aspects such as required permissions, rate limits, or whether the data is cached. The straightforward nature mitigates this somewhat.

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 that efficiently communicates the tool's action and scope without unnecessary words. It is front-loaded with the main verb and resource.

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, the description provides adequate context about the tool's purpose and output fields. However, because there is no output schema, more detail on the return format would 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?

The input schema fully documents the parameter with 100% coverage, and the description adds context by indicating 'any managed instance' and listing the returned info fields. This adds meaning beyond the schema 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 clearly states the tool retrieves detailed server info including hostname, uptime, disk, and memory from any managed instance. This distinguishes it from sibling tools like get_server_memory which focus on specific metrics.

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

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

The description implies the tool is for general server info retrieval but does not explicitly state when to use it versus alternative tools like get_server_memory or cloudwatch_get_log_events. No guidance on prerequisites or exclusions is provided.

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 provided, so description carries full burden. Discloses read-only nature, error code 'missing', format specifics, and redaction of secrets. Could be more transparent about additional error conditions or performance, but is quite detailed overall.

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?

Description is front-loaded with main purpose and usage guidance, then details formats. Every sentence adds value, though length is substantial. Could be slightly more concise but structure is good.

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, so description compensates by explaining return formats and fields (e.g., for 'full' format). Covers error handling, redaction, and format-specific projections. Missing minor details like size limits or additional error codes, but overall complete for the tool's complexity.

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

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

Schema description coverage is 100%, baseline 3. Description adds value by explaining each format's purpose and use case beyond the schema's enum values, and clarifies that instance_id accepts ID, name, or custom-server name.

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

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

The description clearly states the tool returns cached memory (OS, runtimes, services, web stack, logs) for a managed instance. It distinguishes from siblings by advising 'Call FIRST before issuing SSH commands' and directing to build_server_memory when memory is missing.

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 to call this tool first before SSH commands. Provides error handling: if error code 'missing', call build_server_memory then retry. Also details each format's use case (e.g., 'context_block' for prepending to model context, 'stack_summary' for detector recon).

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 fully discloses the tool's mutative nature ('Mutates live traffic rules — confirm with the user first'). It explains the resolution logic for the 'site' parameter and states the return format ('applied/failed split'), leaving no ambiguity about its behavior.

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

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

The description is front-loaded with the primary action and then provides detailed parameter notes. While it is comprehensive, it could be slightly more concise. However, every sentence adds necessary information, and the structure is logical.

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 includes the return format (applied/failed split). It covers all key aspects: purpose, usage modes, parameter interactions, and behavioral caveats. The tool's complexity (7 parameters, two alternative methods) is well-addressed.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the relationship between 'ip_address', 'ip_addresses', and 'cidr', and how 'site' resolves to a WebACL. It provides context beyond the schema descriptions, such as the 'aliases' and 'alternative to config_name'.

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

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

The description specifies that the tool bans or unbans IP(s)/CIDR(s) via either a named WAF/SecurityGroup/NACL config or a site's WebACL. It uses specific verbs ('Ban or unban') and identifies the resource types, clearly distinguishing it from sibling tools like 'block_ip' by detailing the mechanism.

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 explicitly instructs to confirm with the user before use due to live traffic mutation. It outlines two primary methods (config_name vs site) and accepts single or bulk inputs, providing context on when to use each. However, it does not explicitly state when not to use the tool or compare to alternatives beyond mentioning 'ip_ban_list_configs'.

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 explicitly states it is read-only (journalctl over SSH with sudo -n fallback), provides return JSON structure, and lists possible errors. No annotations exist, so description carries full burden.

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 concise with two sentences, front-loading the aggregate summary and providing essential details on behavior, return format, and errors without 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?

The tool has 3 parameters all described in schema, and the description explains return JSON and errors. No output schema exists but description compensates. Minor omission: no mention of pagination or limits.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add significant parameter details beyond the schema. It mentions the lookback window implicitly but not explicitly.

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 it aggregates journald problems on one instance, listing specific items like error-priority entries, OOM kills, restarts, and failed units. It distinguishes from sibling tools (AWS, Docker, etc.) which are unrelated.

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

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

The description implies usage for systemd journal analysis but lacks explicit guidance on when to use this tool versus alternatives. No alternatives are mentioned.

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

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

No annotations are provided, and the description does not disclose behavioral traits such as pagination, authentication requirements, rate limits, or the format of the response. It simply states what the tool does without adding behavioral context beyond the basic listing action.

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 with 14 words, front-loading the verb and resource. Every word is meaningful, and there is no redundancy or 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?

Given the low complexity and full schema coverage, the description covers the core functionality. However, without an output schema, the description could be enhanced by specifying what fields are returned or indicating potential limitations (e.g., no pagination details).

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

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

The description mentions filtering by region or state, but the input schema already provides detailed descriptions for both parameters (including examples for region). Since schema coverage is 100%, the description adds minimal additional semantic value.

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 'List' and the resource 'managed server instances' with specific examples (AWS EC2, OVH, custom servers). It distinguishes the tool from siblings like 'list_server_memories' and 'get_server_info', which have different 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?

The description mentions optional filtering but does not explicitly state when to use this tool versus alternatives (e.g., using 'get_server_info' for a single instance). No guidance on prerequisites or when not to use 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?

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 provided, the description effectively discloses behavioral traits: it is read-only, uses apt-get simulation on Debian/Ubuntu and dnf updateinfo/check-update on RHEL-family, never installs. It also mentions possible error (pkg_manager_not_supported) and return 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 very concise: two sentences plus a note. It front-loads the purpose and quickly covers behavior, supported systems, return format, and errors. No unnecessary 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?

Given the tool's low complexity (one parameter, no output schema), the description is completely sufficient. It covers purpose, behavior, supported systems, return type, and error conditions.

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 has 100% coverage for the single parameter instance_id, and the description adds minimal extra meaning beyond the schema description. The baseline is 3.

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's purpose: checking pending package updates on one instance, including security vs total counts, reboot-required state, and sample package names. It distinguishes itself from sibling tools, none of which focus on package updates.

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

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

The description implies usage when you need pending update info for a specific instance and is read-only, but it does not explicitly state when to use or not use this tool compared to alternatives. No guidance on prerequisites or when to pick a different 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?

The description declares the tool 'Read-only' and lists the metrics it retrieves, giving a clear picture of its behavior. With no annotations provided, it adequately covers the read-only nature and scope, though it could mention that it uses CloudWatch API calls and potential permissions needed.

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

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

The description is extremely concise: two sentences that first state the purpose and metrics, then provide usage context and a parameter note. No unnecessary words, and the most important information comes first.

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

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

The description is complete for a simple snapshot tool: it lists the retrieved metrics, notes read-only access, and provides a specific use case. It does not mention error conditions or pagination, but those are less critical for a tool that likely returns a single snapshot. Overall, it covers the essential context well.

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 has 100% description coverage for all three parameters, each clearly documented. The description adds only a restatement of the 'db_instance' parameter meaning, adding no extra semantics beyond what the schema already provides. Baseline score of 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 action (snapshot) and resource (RDS instance health metrics) and specifies the exact metrics: CPU, connections, CPU credit balance, read/write latency, freeable memory. It also identifies it as the first check for the shared-RDS noisy-neighbour case, distinguishing it from sibling tools.

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

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

The description indicates the tool is the 'first check for the shared-RDS noisy-neighbour case,' implying a specific diagnostic scenario. While it provides clear context, it does not explicitly state when not to use it or list alternatives, leaving some ambiguity.

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 full burden. It discloses that findings are agent-authored and unverified, and advises re-verification. It also explains default behavior (list active findings newest-first) and search capabilities. Missing details on pagination or error handling.

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

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

Five sentences, each serving a purpose: state action, describe parameters, include trust warning. Front-loaded with core functionality. 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?

Covers key behaviors: listing vs. searching, tag filtering, limit, superseded inclusion. No output schema, but description mentions return of full titles and bodies. Could elaborate on output format, but sufficient for agent understanding.

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

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

Schema coverage is 100%, so baseline 3. The description adds marginal value by explaining the query parameter behavior and tag filter logic, but these are already clear from the schema descriptions. No additional nuance beyond 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?

Description clearly states the verb 'recall' and resource 'previously-saved findings for an instance'. It distinguishes this retrieval tool from its write counterpart 'remember_server_finding' and other siblings by specifying the action and output (full titles and bodies).

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 clear when-to-use: listing all findings or searching lexically. Includes a trust caveat about treating findings as leads, not instructions, and re-verifying before destructive actions. However, does not explicitly state when not to use or provide 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?

No annotations are present, so the description carries full burden. It discloses functional equivalence to build_server_memory and states the return format (structured JSON with per-module successes/failures). It does not mention potential side effects beyond cache overwrite, but for a probing tool this is acceptable. Slight lack of detail on idempotency, but overall 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 sentences: purpose, usage distinction with sibling, and return format. Every sentence adds critical information. No redundancy or fluff.

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 (2 params, no output schema), the description covers all necessary aspects: what it does, when to use it, parameters with examples, and return value. No gaps.

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

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

Both parameters are documented in the schema (100% coverage). The description adds value by providing an example for 'modules' and clarifying default behavior ('Omit to refresh all modules'). This goes beyond the schema's description.

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 (re-probe memory modules and overwrite cache) and the resource (memory modules for a managed instance). It explicitly differentiates itself from the sibling tool build_server_memory by specifying when to use each, satisfying the distinction requirement.

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 explicit guidance: use this tool when updating existing memory after a deploy/upgrade, and build_server_memory when no memory exists yet. This clearly tells the agent when to choose this tool over alternatives.

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

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

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.

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

The description implies the tool is for checking relay connection status but does not explicitly state when to use it versus alternatives, nor does it provide when-not-to-use or context. No guidance on prerequisites or exclusions is 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 provided, so description carries full burden. It explains immediate local save, queued sync, return fields, and auto-injection based on confidence. However, it omits error behavior, idempotency, rate limits, and does not explain 'secret_warning' field.

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?

Description is well-structured, front-loading purpose then detailing behavior and return values. Slightly verbose but every sentence adds value; could be tightened without losing clarity.

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 6 parameters, no output schema, and no nested objects, the description adequately covers purpose and key behaviors. Missing details on failure modes and secret_warning; but for an AI agent, the information is sufficient to use the tool correctly in most scenarios.

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. Description adds useful extra context for title (searchable recall key), confidence (threshold for auto-inject), and supersede_id (marks old finding superseded). No significant gaps or contradictions.

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 persists non-obvious, hard-won discoveries about instances, with concrete examples (misconfigured cron, hidden dependency). It distinguishes from sibling tools like list_server_memories and recall_server_findings which are retrieval-focused.

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 context on when to use (for non-obvious findings not visible in fresh probes), describes auto-inject behavior, and reminds to keep title specific. Lacks explicit when-not-to-use or alternatives, but the context is sufficient for an agent to infer use cases.

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 burden of disclosing behavior. It reveals the automatic failover from SSH to SSM when sshd is unreachable, which is a key behavioral trait. It does not discuss permissions, rate limits, or failure modes for non-SSM instances, but the core execution behavior is 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?

The description consists of two concise sentences with no wasted words. The first sentence states the main action and scope, and the second adds critical behavioral detail. It is front-loaded and efficiently communicates the tool's purpose and key 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?

Given the tool has 3 parameters, no output schema, and no annotations, the description covers the main purpose and the notable failover behavior. It does not explain return values or error handling, but the schema covers parameter descriptions well. Overall, it is fairly complete for a reasonably complex 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?

The input schema has 100% description coverage, so baseline is 3. The description adds value by explaining the default transport behavior ('auto' tries SSH then SSM) and the conditions for failover, which is not in the schema. This clarifies the 'transport' parameter's semantics beyond the schema's description.

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's verb ('Run a command') and resource ('any managed instance'), and distinguishes it from sibling tools by specifying the execution mechanism (SSH with SSM failover). It provides specific context about the failover behavior, making 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 explains when to use the tool (for running commands on managed instances) and the automatic failover behavior, which guides selection of the transport parameter. However, it does not explicitly mention when not to use this tool or compare it to alternative siblings like 'get_logs' or 'aws_call', so it slightly lacks clear exclusions.

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