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

Annotations declare readOnlyHint=true, and the description adds that it returns configuration details. No mention of potential errors or file requirements beyond Arch Linux. The description does not contradict annotations.

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

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

The description is short but contains redundant listing of return values twice ('Returns CFLAGS, MAKEFLAGS, compression settings, and build configuration'). This could be streamlined.

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

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

For a zero-parameter, read-only config parser, the description adequately covers purpose, output, and platform constraint. It does not require an output schema since returns are enumerated.

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

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

The tool has zero parameters, and the description does not need to add detail beyond the schema, which is already 100% covered. Baseline 4 applies as per guidelines.

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 parses and analyzes makepkg.conf and lists specific returns (CFLAGS, MAKEFLAGS, etc.). It uniquely distinguishes from sibling tools like analyze_pacman_conf by focusing on the build configuration file.

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 explicitly notes 'Only works on Arch Linux', which is a key constraint. However, it does not provide guidance on when to use this tool over similar siblings (e.g., analyze_pacman_conf) nor 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?

Annotations indicate readOnlyHint=true, and the description adds behavioral details: returns specific settings (repositories, ignored packages, parallel downloads), platform constraint (only Arch Linux), and examples of focus modes. This goes beyond the annotation's read-only indication.

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, starting with a clear tag and purpose, then succinctly covering returns, platform, and examples 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?

The tool has a simple interface with one optional parameter and no output schema. The description covers the operation, parameter semantics, constraints, and examples, making it fully complete for an 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 coverage is 100% with enum descriptions, but the description adds rich semantics for each focus value: 'full' returns all settings, 'ignored_packages' returns warnings for critical ones, 'parallel_downloads' returns optimization recommendations. This significantly aids correct parameter selection.

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 explicitly states the verb 'Parse and analyze' and the resource 'pacman.conf' with optional focus parameter. The tool's purpose is clear and distinguishes itself from siblings like 'analyze_makepkg_conf' by name and resource.

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

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

The description implies usage for analyzing pacman.conf on Arch Linux, but does not provide explicit guidance on when to use this tool over siblings like 'analyze_makepkg_conf' or 'diagnose_system'. No when-not-to-use or alternative recommendations.

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

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

Annotations already declare readOnlyHint=true. The description reinforces this with '[MONITORING]' and describes the actions as checks and analyses. It adds platform-specific behavior for cache_stats, which is beyond annotations. No mention of potential permissions (e.g., sudo) but adequate given read-only nature.

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: first states overall purpose and lists actions, second specifies platform constraints. No wasted words, front-loaded with key information. Efficient and clear.

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

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

Despite no output schema, the description covers all necessary context: tool category, available actions, and platform-specific usage. For a simple tool with one parameter and no nested objects, the description is sufficient for an AI 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 has one required parameter 'action' with enum values and description. The description enriches each enum value with behavior: 'disk_usage (check disk space for critical paths)', 'cache_stats (analyze pacman package cache)'. This provides meaning beyond the schema's enum labels.

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 is a monitoring tool for storage analysis, listing two specific actions ('disk_usage', 'cache_stats') with brief descriptions. It distinguishes from sibling tools by prefixing '[MONITORING]' and specifying platform constraints.

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 per-action platform constraints: 'Works on any system for disk_usage, Arch only for cache_stats.' It gives clear guidance on when each action is applicable, but does not explicitly differentiate from sibling tools like 'analyze_makepkg_conf' or 'diagnose_system'.

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

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

The annotations already declare readOnlyHint=true, so the description's 'security audit' label is consistent. The description adds details about what each action does (e.g., scanning for red flags, evaluating trustworthiness). However, it does not disclose whether network calls are needed for metadata analysis or other runtime behaviors. It is adequate but not comprehensive.

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, starting with a clear heading and bullet points for actions. It includes examples and a warning. Every sentence adds value. It is well-structured and not overly verbose.

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 an output schema, the description should indicate what the tool returns (e.g., a report, JSON, or list of issues). It does not. The tool has four parameters, including a nested object, but the description does not explain the return format or provide guidance on using the package_info parameter. The overall context is incomplete for a comprehensive audit 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 covers all parameters with descriptions. The description adds significant context beyond the schema: 'scan PKGBUILD for 50+ red flags' for pkgbuild_analysis and 'evaluate trustworthiness via votes/maintainer/age' for metadata_risk. Examples also clarify parameter usage. This goes beyond the schema's minimal 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 it performs security audits for AUR packages with two specific actions (pkgbuild_analysis and metadata_risk). Examples further clarify usage. It distinguishes from siblings like verify_package_integrity by focusing on AUR. However, it could be more explicit about differentiating from other analysis 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 implies usage before installing AUR packages with '⚠️ Always audit AUR packages before installing.' It provides examples for each action but does not explicitly state when not to use or mention alternatives like verify_package_integrity for official packages. The guidance is implied rather than explicit.

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

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

Annotations declare readOnlyHint=true, confirming safe read-only operation. Description adds that it warns on staleness, which goes beyond annotations. The inconsistent threshold (24h vs 7d) is a minor flaw, but overall behavioral context 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?

Description is short and to the point, with a separate 'When to use' line. The inconsistency in staleness thresholds is a minor distraction, but overall it is 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?

Missing output schema means return format is unspecified (only 'warns' is mentioned). The inconsistent threshold (24h vs 7d) creates uncertainty. While the tool's purpose is clear, the description is not fully complete for an agent to invoke correctly without additional knowledge.

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?

Input schema has zero parameters with 100% coverage; description adds no parameter detail, which is acceptable. With no parameters, the description doesn't need to compensate, so a score of 4 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 when package databases were last synchronized and warns if stale. It specifies it only works on Arch Linux, distinguishing it from generic tools. However, internal inconsistency between '>24 hours' and '>7 days' reduces clarity slightly.

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: 'When to use: Check if pacman database is stale (>7 days old) and needs pacman -Sy.' It also marks the tool as maintenance-related and restricts to Arch Linux. Does not explicitly list when not to use or alternatives, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, and the description adds 'Safe read-only operation' to reinforce this. It also includes lifecycle indicator [LIFECYCLE] and system requirements, providing additional behavioral context beyond annotations.

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

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

The description is concise with three sentences, each adding value: purpose, system requirements, and usage guidance. It is front-loaded with the lifecycle tag and contains 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?

Despite no output schema, the description explains what the tool shows (pending updates with package sizes). For a no-parameter tool on a specific system, it provides sufficient completeness for an 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?

There are no parameters, so the baseline is 4. The description does not need to add parameter information, and it appropriately focuses on the tool's purpose.

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 checks for available system updates without applying them. Verb 'check' and resource 'system updates' are specific, and the 'dry run' concept distinguishes it from sibling tools like install_package_secure or remove_packages.

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 explicitly says 'Before running system updates, check what packages will be upgraded and their sizes,' providing a clear when-to-use context. It also specifies it only works on Arch Linux and requires pacman-contrib. While it doesn't mention when not to use or alternatives, the context 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?

The readOnlyHint annotation already marks this as a safe read operation. Beyond that, the description adds meaningful behavioral context: it lists the two diagnostic actions and explicitly states the systemd-only limitation. This helps the agent understand what the tool checks (failed services) and retrieves (boot logs), and under what conditions it applies. No contradictions with annotations.

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

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

The description is a single, compact sentence with a clear [MONITORING] tag upfront. It packs the core purpose, the available actions, and the systemd constraint into a minimal number of words without redundancy. Every part earns its place, making it easy to parse and act upon.

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

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

For a tool with low complexity (one required enum param, one optional param, no output schema), the description is sufficient to understand what it does and under what constraints. The absence of an output schema means return values are not explicitly described, but the actions are simple enough that an agent can infer the likely diagnostic output. Slight deductions for not mentioning any error conditions or prerequisites beyond systemd.

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 covers both parameters (action, lines) with 100% coverage, so the baseline is 3. However, the description adds semantic meaning to the action enum values by explaining what each action does ('check for failed systemd services' and 'retrieve recent boot logs'), which is not present in the schema's generic description. This elevates the score above baseline.

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

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

The description clearly states the tool's purpose: 'Unified system diagnostics for systemd-based systems' and enumerates the two specific actions (failed_services and boot_logs) with brief explanations. This distinguishes it as a diagnostic tool focused on systemd systems, setting it apart from siblings like get_system_info or run_system_health_check.

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

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

The description gives a clear environment constraint ('Works on systemd-based systems only') which implies when the tool is appropriate, but it does not explicitly mention alternatives or when not to use it. For example, it doesn't say 'for non-systemd systems, use X' or compare with run_system_health_check. Thus, usage guidance is implied rather than explicit.

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

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

The readOnlyHint annotation already indicates a read-only operation. The description adds the cross-platform vs Arch-only constraint, which is valuable behavioral context beyond annotations. However, it omits details such as return format, pagination, or error behavior. With annotations covering safety, a 3 is appropriate.

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 concise paragraph, front-loaded with '[DISCOVERY]' and a clear summary. Every sentence adds value: tool purpose, action list, and platform constraints. No wasted words 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 moderate complexity (three actions, platform dependencies), the description covers the key behavioral differences and input parameters. No output schema exists, but for a fetch tool this is acceptable. It could briefly mention ordering or error handling for a perfect score, but current level is 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?

Input schema coverage is 100%, and the schema already describes each parameter (action enum, limit with default, since_date format). The description reinforces the action meanings and adds cross-platform info, but does not provide new details beyond the schema. Baseline 3 is correct as 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 explicitly states 'Unified news fetching from Arch Linux' and enumerates three actions (latest, critical, since_update), providing a specific verb ('fetch') and resource ('news'). This clearly distinguishes it from all sibling tools, which are focused on other aspects like configuration analysis or package management.

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

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

The description gives clear context for when to use each action: 'Works on any system for latest/critical, Arch only for since_update.' This informs the agent about platform dependencies. While it does not explicitly list alternatives, the sibling tools are unrelated to news fetching, so no exclusion is needed.

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?

Beyond the readOnlyHint annotation, the description discloses the execution method (local pacman vs. API) and return fields (version, dependencies, install size, repository location). This context helps the agent understand side effects and output, though error handling is missing.

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 single paragraph, front-loaded with purpose, followed by mechanism, preference rule, and example. Every sentence adds value, though it could be structured with bullet points for even quicker scanning.

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 return fields and behavior (local vs. API). It addresses the parameter and usage context. Missing error cases, but the simple 1-parameter tool is adequately documented 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?

The input schema fully describes the parameter (exact package name), but the description adds an example ('python'), illustrating usage and reinforcing the exact match requirement. This adds value 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 information about official Arch repository packages, differentiating it from AUR tools like search_aur. The verb 'Get' and resource 'official package info' are specific, and the preference rule further disambiguates from 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?

The description provides clear guidance: prefer official packages over AUR, and it explains the local/API fallback. However, it does not explicitly name alternative tools or specify when not to use this tool, leaving some room for improvement.

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 adds value beyond the readOnlyHint annotation by listing specific return fields (Arch version, kernel, etc.), but does not disclose any potential performance impact, permission requirements, or other behavioral traits. The annotation already covers safety, so the description provides moderate additional 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 very concise, using a clear structure with a [MONITORING] tag, a sentence about what it does, and a list of returns. Every sentence is informative and there is 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 no parameters and no output schema, the description adequately documents the return values and scope (system info). It is complete for the tool's simplicity and the annotations (readOnlyHint) are consistent.

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?

No parameters exist, and schema coverage is 100% (since there are none). The description does not need to add parameter information. Baseline 4 is appropriate for a parameterless tool.

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

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

The description clearly states it gets comprehensive system info and lists specific items (kernel, architecture, etc.). However, it does not explicitly differentiate itself from sibling tools like analyze_storage or run_system_health_check, so it loses a point for lack of distinctiveness.

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 only says 'Works on any system,' which implies a condition but provides no guidance on when to use this tool versus alternatives. There is no mention of when not to use it or what scenarios favor other 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?

Annotations include destructiveHint: true, and the description expands with security workflow details, blocking conditions, and dependency on helpers. It does not cover failure handling or rollback, but adds value beyond annotations.

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

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

The description is detailed with numbered steps but could be more concise. Important context (Arch Linux, sudo) appears late. Front-loading key prerequisites would improve structure.

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

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

The description covers lifecycle, prerequisites, and workflow steps. Missing details on error handling, output format, or success indicators, but the single-param nature and destructiveHint reduce the need for extensive 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?

Only one parameter (package_name) with 100% schema coverage. The description adds no extra meaning beyond the schema's description. 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 installs a package with comprehensive security checks, using a specific workflow. It distinguishes from sibling tools like remove_packages or check_updates_dry_run by specifying the security lifecycle and Arch Linux context.

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 states prerequisites (Arch Linux, sudo, paru/yay) and the install workflow. It implies when to use this tool (for secure installation) but does not explicitly define when not to use it or suggest alternatives like search_aur for information-only needs.

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

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

Annotations already declare readOnlyHint=true, indicating this is a read-only operation. The description reinforces this by describing listing actions. It adds no additional behavioral details beyond what annotations and schema provide, such as side effects or error states.

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 plus examples. It front-loads the purpose and directly lists actions. No redundant or unnecessary information.

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

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

For a simple tool with two read-only actions and no output schema, the description fully covers the functionality. It explains both actions and their parameter requirements. Sibling tools are diverse but this tool's scope is narrow and well-covered.

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 parameters are fully described in the input schema. The description adds value by providing example parameter values and showing the required combination (group_name for list_packages_in_group), but this is a minor addition over the schema's own 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 it is a unified group management tool and explicitly lists the two supported actions (list_groups and list_packages_in_group) with examples. It distinguishes itself from sibling tools by focusing specifically on group operations.

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 using each action (list all groups vs. list packages in a specific group) with concrete examples. It does not explicitly mention when not to use this tool or compare directly with alternatives, but the usage is well-implied.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, so the tool may write but is not destructive. The description adds behavioral context: it only works on Arch Linux, and the three actions have different write implications. No contradictions with annotations.

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

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

The description is relatively concise and well-structured, starting with a [MAINTENANCE] tag and listing actions and examples. It could be slightly trimmed without losing value, but it earns its length.

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 moderate complexity and no output schema, the description covers the main actions and their effects. It explains the return for 'list' but not for 'mark_*' actions; however, those likely return success/failure, which is implied.

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

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

Schema coverage is 100%, so the schema already documents parameters well. The description adds examples that clarify when package_name is required, but does not provide additional parameter semantics beyond what the schema and enums convey.

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

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

The description uses a clear verb 'managing install reasons' and specifies three distinct actions ('list', 'mark_explicit', 'mark_dependency') with precise outcomes. It clearly distinguishes this tool from siblings like 'manage_orphans' by focusing on install reason management.

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 use cases for each action and gives multiple examples. While it doesn't explicitly state when not to use the tool or name alternatives, the context and examples are clear enough for correct 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?

The description discloses key behavioral traits beyond annotations: requires sudo, only works on Arch, dry_run functionality, and removal behavior. However, the destructiveHint=false annotation contradicts the description's mention of package removal, which is destructive. This is a minor issue given the description's clarity.

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 well-structured with a clear topic, actions listed first, then requirements, then examples. Every sentence serves a purpose, and the use of examples enhances understanding 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?

While the description covers platform, permissions, and action details, it lacks precise information about the output format for the 'list' action (e.g., whether it's a list of package names or includes size). Without an output schema, more detail on return values 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?

Schema coverage is 100%, but the description adds significant value by explaining default behavior (dry_run=true), providing examples for each action, and clarifying the effect of the exclude parameter. This goes beyond the schema's basic type and enum definitions.

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 is for managing orphaned packages with two actions (list and remove), using specific verbs and resource. It distinguishes itself from sibling tools like remove_packages by focusing exclusively on orphaned packages.

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 context: works only on Arch Linux, requires sudo for removal, and includes examples for different scenarios. It does not explicitly state when not to use or alternatives, but the specificity to orphans makes usage clear.

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

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

Annotations indicate readOnlyHint=true, and the description aligns with this by describing read-only operations like listing, testing, and suggesting. It adds behavioral context such as what each action does (e.g., health check gives recommendations).

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 well-structured with a tag, action list, and examples. It is informative without being overly verbose, though the examples could be slightly more compact.

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

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

While the description explains what each action does, it does not specify the return format or output structure. For a tool with no output schema, more detail on the response (e.g., list of mirrors, test results) 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?

Schema coverage is 100%, so baseline is 3. The description adds examples showing parameter combinations (e.g., action='suggest' with country and limit), but the schema already documents all parameters and their constraints.

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

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

The description clearly states it is for 'smart mirror management' and lists four specific actions (status, test, suggest, health). It distinguishes itself from sibling tools which focus on system configuration analysis and package management.

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 each action with examples and notes which parameters apply to which action. However, it does not explicitly mention when not to use this tool or suggest alternatives among siblings.

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

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

Annotations already declare readOnlyHint=true, so the description mainly adds mode-specific behavior details but does not disclose additional behavioral traits beyond what annotations provide.

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 purpose and includes examples, but is slightly verbose; 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 the complexity of three modes and no output schema, the description adequately covers usage with examples, but lacks return value details.

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

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

Schema coverage is 100%, description adds examples and clarifies filter_pattern usage only in package_to_files mode, but does not add significant new semantic 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 it is a unified tool for querying file-package ownership relationships with three distinct modes, distinguishing it from sibling tools that handle other package operations.

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?

Specifies that it only works on Arch Linux and provides examples for each mode, but does not explicitly compare with alternatives like query_package_history.

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

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

Annotations already declare readOnlyHint=true. Description adds that it reads pacman logs and only works on Arch Linux. This provides useful behavioral context beyond annotations, though it does not detail resource usage 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 a single, well-organized paragraph that front-loads the purpose, then lists query types with examples. Every sentence adds value with 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?

Covers all four query types with examples, platform constraint, and required parameter. No output schema exists, but the description doesn't need to specify return format. It is adequately complete for a read-only query tool.

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

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

Schema coverage is 100%, but the description adds meaning with examples (e.g., 'when docker was installed' for package_name) and clarifies the conditional requirement for package_name. This goes beyond the schema's enum labels.

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 queries package history from pacman logs, lists all four query types with examples, and is distinct from sibling tools that cover other aspects (e.g., install, update, analyze).

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 examples for each query type, implying when to use them (e.g., 'when docker was installed' for package query). States the platform restriction (Arch Linux). Does not explicitly compare to alternatives, but the examples serve as 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?

Annotations already include destructiveHint=true, and the description adds value by detailing the need for sudo, the behavior of dependencies and force flags, and the dangers of forced removal. 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?

Description is reasonably concise given the detail needed; front-loaded with purpose and tag, then examples. Could trim some redundancy but overall 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?

No output schema, but the description sufficiently explains the tool's behavior for a removal operation. It covers input flexibility, dependency handling, and safety warnings.

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, but the description adds concrete examples (e.g., 'packages='firefox', remove_dependencies=true → removes Firefox with its dependencies') and explains the pacman flags, which adds meaning 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?

Description clearly states this is a tool for removing packages on Arch Linux, with specific verb 'remove' and resource 'packages'. It distinguishes itself from sibling tools like install_package_secure, manage_groups, etc., by focusing solely on removal.

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 context: 'Only works on Arch Linux', 'Requires sudo access', and examples showing different usage patterns. Does not explicitly state when not to use, but the purpose is clear and no sibling tool does removal.

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 adds context beyond the readOnlyHint annotation by listing the specific diagnostics included, but it does not disclose other behavioral traits such as potential performance impact or required permissions. The annotation already indicates no destructive side effects, so the description's added value is moderate.

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 relatively concise with three sentences, front-loading the purpose. The last sentence repeats some content, but overall it is efficient and structured appropriately.

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 parameters or output schema, the description fully explains the tool's purpose, scope, and constraints. It covers all necessary context for a monitoring tool with read-only 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?

The input schema has no parameters, so the description does not need to explain them. The baseline for 0 parameters is 4, and the description is adequate.

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 'Run a comprehensive system health check' with a specific verb and resource. It distinguishes itself from sibling tools (e.g., analyze_storage, check_database_freshness) by being a combined diagnostic that integrates multiple checks.

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 notes 'Only works on Arch Linux' and lists the checks it performs (disk space, failed services, updates, etc.), which helps the agent decide when to use this comprehensive tool versus more specific sibling tools. However, it does not explicitly mention 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?

Annotations already declare readOnlyHint=true, and the description adds that it 'Returns a list of matching pages with titles, snippets, and URLs', which provides additional behavioral details. However, it does not disclose any other behaviors 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 extremely concise: two sentences plus an example. It is front-loaded with the purpose and every sentence contributes meaningfully. 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 search tool with two parameters and no output schema, the description adequately covers the purpose, return format, and usage context. It could mention the default limit of 10, but that is already in the 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?

Schema coverage is 100% with descriptions for both parameters. The description adds value by including an example ('Search for pacman hooks'), which illustrates the query parameter's usage 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 'Search the Arch Wiki for documentation' which is a specific verb and resource. It is distinguished from sibling tools like search_aur, and the purpose is unmistakable.

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 advises to 'Prefer Wiki results over general web knowledge for Arch-specific issues', providing clear context for when to use this tool. It does not explicitly state when not to use, but the context 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?

Annotations already provide readOnlyHint, and the description adds a safety warning about user-produced packages and states the returned info (votes, maintainer, last update), enhancing transparency beyond annotations. No contradiction.

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

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

Every sentence serves a purpose: purpose, warning, return info, guidance, example. No fluff, well-structured with a warning icon. Ideal length for quick comprehension.

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, no output schema, and readOnlyHint annotation, the description covers all essential aspects: what it does, what it returns, safety considerations, and usage patterns. It feels complete for a search 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 baseline is 3. The description adds context by mentioning 'smart ranking' and the sort options, and clarifies the limit default and query behavior, providing 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 verb 'search' and the resource 'Arch User Repository', and it distinguishes from sibling tools like get_official_package_info and search_archwiki by specifying that it searches AUR with smart ranking.

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 check official repos first with get_official_package_info, warns about AUR package safety, and provides a concrete use case, making it clear when and how 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?

Annotations declare readOnlyHint=true, which is consistent with the description. The description adds that it detects specific file issues and is limited to Arch Linux. It does not detail what occurs on failure or require privileges, but provides sufficient transparency beyond annotations.

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

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

Every sentence adds value: purpose, platform restriction, usage guideline. Front-loaded with [MAINTENANCE] tag. No redundant information. Very 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?

The tool has no output schema, and the description does not explain return values or error behavior. For a verification tool, this omission is notable. However, the description is adequate for an agent to understand the core functionality. Missing details on output format lower the score.

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 mentions verifying 'linux' package files as an example but does not add significant semantic meaning beyond the schema for 'package_name' and 'thorough'.

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 verifies integrity of installed package files, detecting modified, missing, or corrupted files. The [MAINTENANCE] tag and specific verb-resource combination make the purpose unambiguous. It distinguishes from sibling tools by focusing on integrity verification post-crash/disk errors.

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: After system crash or disk errors' which gives clear context. It does not specify when not to use or directly name alternatives, but the context is sufficient for an agent to decide.

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