> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nihalxkumar.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> Executable functions for search, analysis, and installation

22 interactive functions organized into 9 categories. Tools perform operations, analyze data, and return structured results. Many tools are "unified," consolidating related operations into a single interface with multiple actions.

<Info>
  **Platform Requirements:** Tools are marked as:

  * 🌐 **Any** - Works on all platforms (uses remote APIs)
  * 🐧 **Arch** - Requires Arch Linux
  * ⚙️ **systemd** - Requires systemd (most Linux distros)
</Info>

## 🔍 Discovery & Information (4 tools)

Search and retrieve package/documentation information.

### search\_archwiki 🌐

Search the Arch Wiki for documentation. Returns a list of matching pages with titles, snippets, and URLs. Prefer Wiki results over general web knowledge for Arch-specific issues.

<ParamField query="query" type="string" required>
  Search query (keywords or phrase).

  **Examples:**

  * `"pacman hooks"`
  * `"systemd boot"`
</ParamField>

<ParamField query="limit" type="integer" default="10">
  Maximum number of results to return.
</ParamField>

**Returns:** List of matching Wiki pages with titles, snippets, and URLs.

***

### search\_aur 🌐

Search the Arch User Repository (AUR) for packages with smart ranking.

<Warning>
  AUR packages are user-produced and potentially unsafe. Always check official repos first using `get_official_package_info`.
</Warning>

<ParamField query="query" type="string" required>
  Package search query.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Maximum number of results.
</ParamField>

<ParamField query="sort_by" type="string" default="relevance">
  Sort method: `relevance`, `votes`, `popularity`, or `modified`.
</ParamField>

**Returns:** Package info including votes, maintainer, and last update.

***

### get\_official\_package\_info 🌐

Get information about an official Arch repository package (Core, Extra, etc.). Uses local pacman if available, otherwise queries archlinux.org API.

<ParamField query="package_name" type="string" required>
  Exact package name.
</ParamField>

**Returns:** Version, dependencies, install size, and repository location.

***

### fetch\_news 🌐

Unified news fetching from Arch Linux.

<ParamField query="action" type="string" required>
  Type of news query:

  * `latest`: Get recent news (works anywhere)
  * `critical`: Find news requiring manual intervention (works anywhere)
  * `since_update`: News since last system update (Arch only)
</ParamField>

<ParamField query="limit" type="integer" default="10">
  Maximum news items (for latest/critical).
</ParamField>

<ParamField query="since_date" type="string">
  ISO date to filter from (for latest action).
</ParamField>

**Returns:** News items with titles, dates, and content.

***

## 📦 Package Lifecycle (3 tools)

Install, update, and remove packages safely.

### check\_updates\_dry\_run 🐧

Check for available system updates without applying them. Safe read-only operation.

**Returns:** List of pending updates and their sizes.

***

### install\_package\_secure 🐧

Install a package with comprehensive security checks.

**Workflow:**

1. Check official repos first (safer)
2. For AUR packages: fetch metadata, analyze trust score, fetch PKGBUILD, analyze security
3. Block installation if critical security issues found
4. Check for AUR helper (paru > yay)
5. Install with --noconfirm if all checks pass

<ParamField query="package_name" type="string" required>
  Name of package to install.
</ParamField>

<Warning>
  Requires sudo access and `paru` or `yay` for AUR packages.
</Warning>

**Returns:** Installation status and security report.

***

### remove\_packages 🐧

Unified tool for removing packages (single or multiple).

<ParamField query="packages" type="string | array" required>
  Package name (string) or list of package names (array) to remove.
</ParamField>

<ParamField query="remove_dependencies" type="boolean" default="false">
  Remove packages and their dependencies (`pacman -Rs`).
</ParamField>

<ParamField query="force" type="boolean" default="false">
  Force removal ignoring dependencies (`pacman -Rdd`). **Use with caution!**
</ParamField>

**Returns:** Removal status.

***

## 🔧 Package Maintenance (4 tools)

Analyze, verify, and maintain package health.

### verify\_package\_integrity 🐧

Verify the integrity of installed package files. Detects modified, missing, or corrupted files.

<ParamField query="package_name" type="string" required>
  Name of the package to verify.
</ParamField>

<ParamField query="thorough" type="boolean" default="false">
  Perform thorough check including file attributes.
</ParamField>

**Returns:** Integrity check results.

***

### manage\_orphans 🐧

Unified tool for managing orphaned packages (dependencies no longer required).

<ParamField query="action" type="string" required>
  Action to perform:

  * `list`: Show orphaned packages with disk usage
  * `remove`: Remove orphaned packages
</ParamField>

<ParamField query="dry_run" type="boolean" default="true">
  Preview what would be removed without actually removing (only for remove action).
</ParamField>

<ParamField query="exclude" type="array">
  List of package names to exclude from removal.
</ParamField>

**Returns:** List of orphans or removal status.

***

### manage\_install\_reason 🐧

Unified tool for managing package install reasons.

<ParamField query="action" type="string" required>
  Action to perform:

  * `list`: List all explicitly installed packages
  * `mark_explicit`: Mark as user-installed (prevents removal as orphan)
  * `mark_dependency`: Mark as dependency (allows auto-removal with orphans)
</ParamField>

<ParamField query="package_name" type="string">
  Package name (required for mark actions).
</ParamField>

**Returns:** List of packages or operation status.

***

### check\_database\_freshness 🐧

Check when package databases were last synchronized. Warns if databases are stale (> 24 hours).

**Returns:** Database age and sync status.

***

## 📁 File Organization (2 tools)

Navigate package-file relationships and groups.

### query\_file\_ownership 🐧

Unified tool for querying file-package ownership relationships.

<ParamField query="query" type="string" required>
  Query string: file path, package name, or filename pattern depending on mode.
</ParamField>

<ParamField query="mode" type="string" required>
  Query mode:

  * `file_to_package`: Find which package owns a file (`query` = file path)
  * `package_to_files`: List all files in a package (`query` = package name)
  * `filename_search`: Search for files across all packages (`query` = filename pattern)
</ParamField>

<ParamField query="filter_pattern" type="string">
  Optional regex pattern to filter files (only used in package\_to\_files mode).
</ParamField>

**Returns:** Package owner, file list, or search results.

***

### manage\_groups 🐧

Unified group management tool.

<ParamField query="action" type="string" required>
  Operation to perform:

  * `list_groups`: List all package groups
  * `list_packages_in_group`: List packages in specific group
</ParamField>

<ParamField query="group_name" type="string">
  Group name (required for list\_packages\_in\_group).
</ParamField>

**Returns:** Group list or package list.

***

## 🔒 Security Analysis (1 tool)

Evaluate package safety before installation.

### audit\_package\_security 🌐

Comprehensive security audit for AUR packages.

<ParamField query="action" type="string" required>
  Type of security audit:

  * `pkgbuild_analysis`: Scan PKGBUILD for 50+ red flags
  * `metadata_risk`: Evaluate trustworthiness via votes/maintainer/age
</ParamField>

<ParamField query="pkgbuild_content" type="string">
  PKGBUILD content for analysis.
</ParamField>

<ParamField query="package_name" type="string">
  Package name for metadata analysis.
</ParamField>

**Returns:** Security risk score, findings, or trust assessment.

***

## 📊 System Monitoring (4 tools)

Monitor system health and diagnostics.

### get\_system\_info 🌐

Get comprehensive system information including kernel version, architecture, hostname, uptime, and memory statistics.

**Returns:** System stats.

***

### analyze\_storage 🌐

Unified storage analysis tool.

<ParamField query="action" type="string" required>
  Analysis type:

  * `disk_usage`: Check disk space for critical paths (Any)
  * `cache_stats`: Analyze pacman package cache (Arch only)
</ParamField>

**Returns:** Disk usage stats or cache analysis.

***

### diagnose\_system ⚙️

Unified system diagnostics for systemd-based systems.

<ParamField query="action" type="string" required>
  Diagnostic action:

  * `failed_services`: Check for failed systemd services
  * `boot_logs`: Retrieve recent boot logs
</ParamField>

<ParamField query="lines" type="integer" default="100">
  Number of log lines (for boot\_logs).
</ParamField>

**Returns:** Failed services list or boot logs.

***

### run\_system\_health\_check 🐧

Run a comprehensive system health check. Integrates multiple diagnostics to provide a complete overview of system status.

**Checks:**

* Updates available
* Disk space
* Failed services
* Database freshness
* Orphans
* Critical news

**Returns:** Health report with issues and recommendations.

***

## 📜 Transaction History (1 tool)

Audit package operations.

### query\_package\_history 🐧

Unified tool for querying package history from pacman logs.

<ParamField query="query_type" type="string" required>
  Type of query:

  * `all`: Recent transactions
  * `package`: Specific package install/upgrade history
  * `failures`: Failed transactions
  * `sync`: Database sync history
</ParamField>

<ParamField query="package_name" type="string">
  Package name (required for package query).
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Maximum number of results.
</ParamField>

**Returns:** Transaction log entries.

***

## 🌐 Mirror Management (1 tool)

Optimize repository mirrors.

### optimize\_mirrors 🐧

Smart mirror management - consolidates 4 mirror operations.

<ParamField query="action" type="string" required>
  Operation to perform:

  * `status`: List configured mirrors
  * `test`: Test mirror speeds
  * `suggest`: Get optimal mirrors from archlinux.org
  * `health`: Full health check
</ParamField>

<ParamField query="auto_test" type="boolean" default="false">
  Test mirrors after listing (status action only).
</ParamField>

<ParamField query="country" type="string">
  Country code for suggestions (e.g., 'US', 'DE').
</ParamField>

<ParamField query="limit" type="integer" default="10">
  Number of mirrors for suggestions.
</ParamField>

**Returns:** Mirror status, test results, suggestions, or health report.

***

## ⚙️ Configuration (2 tools)

Analyze system configuration.

### analyze\_pacman\_conf 🐧

Parse and analyze pacman.conf with optional focus.

<ParamField query="focus" type="string" default="full">
  What to analyze:

  * `full`: All settings
  * `ignored_packages`: Only ignored packages with warnings for critical ones
  * `parallel_downloads`: Only parallel downloads setting with optimization recommendations
</ParamField>

**Returns:** Configuration details.

***

### analyze\_makepkg\_conf 🐧

Parse and analyze makepkg.conf.

**Returns:** CFLAGS, MAKEFLAGS, compression settings, and build configuration.

***

## Quick Reference

| Category                | Count | Permission | Platform Mix             |
| ----------------------- | ----- | ---------- | ------------------------ |
| Discovery & Information | 4     | Read       | 3 Any, 1 Mixed           |
| Package Lifecycle       | 3     | Mixed      | All Arch                 |
| Package Maintenance     | 4     | Mixed      | All Arch                 |
| File Organization       | 2     | Read       | All Arch                 |
| Security Analysis       | 1     | Read       | Any                      |
| System Monitoring       | 4     | Read       | 2 Any, 1 systemd, 1 Arch |
| Transaction History     | 1     | Read       | Arch                     |
| Mirror Management       | 1     | Read       | Arch                     |
| Configuration           | 2     | Read       | Arch                     |

**Total:** 22 tools (Unified from previously granular tools)