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

# System Tools

> Platform capabilities: code execution, packages, introspection

System tools are opt-in platform capabilities beyond the normal function/query toolkit. Enable them via the `system_tools` property on agents. Each tool is either a simple string (no config needed) or an object with a `name` and tool-specific configuration.

```yaml theme={null}
agents:
  - name: my-agent
    systemTools:
      - codeExecution
      - packageManagement
      - configIntrospection
      - name: databaseIntrospection
        connections:
          - built-in
          - analytics-db
```

**Available system tools:**

| Tool                    | Type   | Description                                                                                                                                   |
| ----------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `codeExecution`         | string | Generate and execute Python code in sandboxed containers                                                                                      |
| `configIntrospection`   | string | Read-only inspection of the current Sinas configuration: list resource types, browse resources by name/description, read full resource detail |
| `packageManagement`     | string | Validate, preview, install, and uninstall Sinas packages. Install and uninstall require user approval.                                        |
| `databaseIntrospection` | object | Read-only schema inspection of database connections. Requires `connections` list specifying which connections the agent can access.           |

**Config introspection tools:**

* `sinas_config_inspect` — Resource type counts (overview)
* `sinas_config_list(type, namespace?)` — Names + descriptions for a type
* `sinas_config_get(type, namespace, name)` — Full detail of one resource

**Package management tools:**

* `sinas_package_validate(yaml)` — Validate package YAML (syntax + schema)
* `sinas_package_preview(yaml)` — Dry-run install (shows what would change)
* `sinas_package_install(yaml)` — Install package (requires approval)
* `sinas_package_uninstall(name)` — Uninstall package (requires approval)
* `sinas_package_list()` — List installed packages
* `sinas_package_export(name)` — Export package as YAML

**Database introspection tools:**

* `sinas_db_list_tables(connectionName)` — List tables with schemas, types, row counts, and table annotations
* `sinas_db_describe_table(table, connectionName, schema?)` — Columns, types, indexes, foreign keys, and column annotations

The `databaseIntrospection` tool requires a `connections` list. The agent can only introspect connections listed in its config. This uses the same connection pool as regular queries and includes annotations from the semantic layer (table/column display names and descriptions).

**Collection file tools (readwrite access):**

When an agent has `access: readwrite` on an enabled collection, it gets additional tools:

* `write_file_{ns}_{name}(filename, content)` — Write/overwrite a file (creates new version)
* `edit_file_{ns}_{name}(filename, old_string, new_string)` — Surgical edit via exact string replacement
* `delete_file_{ns}_{name}(filename)` — Delete a file

These are in addition to the read tools (`search_collection_*`, `get_file_*`) that every enabled collection provides. `get_file` supports `offset` and `limit` parameters for reading specific line ranges of large files.