# Tool Catalog

Coda's tools are organized across **12 categories** plus **5 skill aggregators**. All tools are **read-only** — no write operations (except `execute_code` which runs sandboxed code on the runner service).

Tools with optional infrastructure dependencies (Snowflake, GraphQL) declare their own runtime availability via an `enabled()` predicate and are automatically excluded when their backing service is unavailable.

```mermaid
graph TD
    skills["Skills (5)"] --> account_skill["account_overview"]
    skills --> contract_skill["contract_overview"]
    skills --> revenue_skill["revenue_overview"]
    skills --> graphql_skill["graphql_explore"]
    skills --> snowflake_skill["snowflake_explore"]

    categories["Tool Categories"] --> account["Account (7)"]
    categories --> royalties["Royalties (14)"]
    categories --> moneyhub["Moneyhub (5)"]
    categories --> product["Product (3)"]
    categories --> ledger["Ledger (9)"]
    categories --> file["File (2)"]
    categories --> snowflake["Snowflake (3)"]
    categories --> graphql["GraphQL (3)"]
    categories --> search["Search (1)"]
    categories --> notion["Notion (3)"]
    categories --> adjustments["Adjustments (7)"]
    categories --> runner["Runner (3)"]
```

## What Coda can and can't do

**Can do:** Look up any account, contract, or product. Analyze revenue by period, store, artist, or transaction type. Check ledger balances and pending adjustments. Query Snowflake agent-consumable views. Explore and query the GraphQL gateway schema. Generate Excel/PDF exports. Search by name, UPC, or ISRC. Show advance history, payment holds, tax info, and contract terms.

**Cannot do:** Modify any data (all tools are read-only). Access services outside the listed backends. Perform actions on behalf of a user (e.g. place a payment hold, create a contract). Write to Snowflake or execute mutations via GraphQL.

## Skills (5 tools)

High-level aggregation tools that fetch multiple data points in a single call. Use these for broad questions; individual tools handle targeted follow-ups.

| Tool                      | Service(s)      | What it does                                                                                       |
| ------------------------- | --------------- | -------------------------------------------------------------------------------------------------- |
| `account_overview_skill`  | Multiple        | Account details, payment terms, eligibility, tax info, activity summary, and contracts in one call |
| `contract_overview_skill` | Multiple        | Contract details, enriched terms with conditions, all advances, parties, and lifecycle             |
| `revenue_overview_skill`  | Multiple        | Statement periods with revenue, activity summary, revenue by store and artist with totals          |
| `snowflake_explore_skill` | Snowflake       | Discover agent-consumable views and run read-only queries. Requires Snowflake pool                 |
| `graphql_explore_skill`   | GraphQL gateway | Explore the federated GraphQL schema and execute read-only queries. Requires gateway URL           |

## Search (1 tool)

| Tool           | What it does                                                                           |
| -------------- | -------------------------------------------------------------------------------------- |
| `search_tools` | Catalog-aware tool discovery by keyword — helps Claude find the right tool for a query |

## Account tools

Source: **ows-abacus-account**

| Tool                               | What it does                                                       |
| ---------------------------------- | ------------------------------------------------------------------ |
| `search_accounts`                  | Search accounts by name. Returns paginated list with IDs and names |
| `get_account_payee`                | Payee/payment-method info including Payoneer details               |
| `get_account_payment_hold`         | Current payment hold status, reason, start date, creator           |
| `get_account_payee_history`        | Historical payee changes for an account                            |
| `get_account_tax_info_history`     | Historical tax info changes for an account                         |
| `get_account_payment_hold_history` | Historical payment hold changes for an account                     |
| `get_reference_agreement_types`    | List available agreement types                                     |

## Royalties tools

Source: **ows-royalties**

| Tool                                         | What it does                                                                |
| -------------------------------------------- | --------------------------------------------------------------------------- |
| `search_contracts`                           | Search contracts by name or filter by account ID                            |
| `get_historical_advances`                    | Historical advance payment records for a contract                           |
| `get_contract_exclusions`                    | Territory or other exclusions defined in a contract                         |
| `find_contract_terms_by_attachment`          | Find contract terms that reference a specific ISRC or UPC within an account |
| `get_statement_periods`                      | Statement periods for an account                                            |
| `get_current_statement_period`               | Current open statement period                                               |
| `get_recent_statement_periods`               | Recently closed statement periods                                           |
| `get_upcoming_statement_periods`             | Upcoming future statement periods                                           |
| `get_statement_period`                       | Details for a specific statement period by ID                               |
| `get_run_controller_by_contract`             | Run controller status for a contract                                        |
| `get_run_controller_contracts_by_account`    | Run controller contracts for an account                                     |
| `get_accounting_periods`                     | Accounting periods                                                          |
| `get_statement_period_payment_entities`      | Payment entities for a statement period                                     |
| `get_statement_period_payment_entity_states` | Payment entity states for a statement period                                |

## Financial / Moneyhub tools

Source: **ows-moneyhub** (Snowflake-backed `/revenue-analysis/` endpoints)

| Tool                                      | What it does                                                             |
| ----------------------------------------- | ------------------------------------------------------------------------ |
| `get_account_statement_periods`           | Statement periods with per-period gross and net revenue                  |
| `get_account_revenue_by_store`            | Revenue breakdown by digital store (Spotify, Apple Music, etc.)          |
| `get_account_revenue_by_artist`           | Revenue breakdown by artist                                              |
| `get_account_revenue_by_transaction_type` | Revenue breakdown by transaction type (streaming, downloads, sync, etc.) |
| `get_account_revenue_by_subaccount`       | Revenue breakdown by subaccount                                          |

## Ledger tools

Source: **ows-ledger**

| Tool                              | What it does                                        |
| --------------------------------- | --------------------------------------------------- |
| `get_account_current_balance`     | Current ledger balance for an account               |
| `get_account_payable_balance`     | Payable balance breakdown by contract               |
| `get_account_ledger_contracts`    | Contracts with ledger entries for an account        |
| `get_pending_ledger_adjustments`  | Pending corrections/adjustments awaiting processing |
| `get_ledger_reserve_releases`     | Reserve release history for an account              |
| `get_reference_adjustment_types`  | List available adjustment types                     |
| `get_account_ledger_adjustments`  | Ledger adjustment history for an account            |
| `get_moneyhub_ledger_adjustments` | Moneyhub-sourced ledger adjustments                 |
| `get_adjustment_files`            | Files associated with ledger adjustments            |

## Product tools

Source: **ows-product**

| Tool                   | What it does                                         |
| ---------------------- | ---------------------------------------------------- |
| `get_product`          | Product (release) details by product ID              |
| `get_product_by_upc`   | Look up a product by UPC barcode                     |
| `get_products_by_isrc` | Find products containing a track with the given ISRC |

## File generation tools

Source: **Local (in-process)**

| Tool             | What it does                                                       |
| ---------------- | ------------------------------------------------------------------ |
| `generate_excel` | Generates a downloadable .xlsx file from structured tabular data   |
| `generate_pdf`   | Generates a downloadable PDF with headings, paragraphs, and tables |

## Snowflake tools (conditional)

Source: **Snowflake** — requires Snowflake reader pool (`SNOWFLAKE_READER_*` env vars)

| Tool                       | What it does                                                                          |
| -------------------------- | ------------------------------------------------------------------------------------- |
| `search_snowflake_schema`  | Hybrid search (keyword + semantic + glossary) over the schema index with FK neighbors |
| `describe_snowflake_table` | Get column schema for a specific table or view                                        |
| `query_snowflake`          | Execute read-only SQL queries (SELECT/WITH only, auto-limited to 500-1000 rows)       |

## GraphQL tools (conditional)

Source: **GraphQL federation gateway** — requires `GRAPHQL_GATEWAY_URL`

| Tool                | What it does                                                                   |
| ------------------- | ------------------------------------------------------------------------------ |
| `search_graphql`    | Search the federated gateway schema by keyword                                 |
| `graphql_type_info` | Inspect a GraphQL type's fields and relationships                              |
| `query_graphql`     | Execute read-only GraphQL queries (variables supported, introspection blocked) |

## Notion tools (conditional)

Source: **Notion API** — requires active OAuth connection

| Tool                    | What it does                                              |
| ----------------------- | --------------------------------------------------------- |
| `search_notion`         | Search pages and databases in the user's Notion workspace |
| `read_notion_page`      | Read the full content of a Notion page as markdown        |
| `query_notion_database` | Query a Notion database with optional filters and sorts   |

## Adjustment tools

Source: **ows-ledger** / **ows-royalties**

| Tool                                  | What it does                                                                 |
| ------------------------------------- | ---------------------------------------------------------------------------- |
| `get_adjustment_types`                | Returns the authoritative list of valid adjustment type names                |
| `get_statement_period_for_adjustment` | Returns the current open statement period for targeting an adjustment batch  |
| `validate_adjustment_file`            | Pre-validates an uploaded adjustment Excel file (headers, rows, types)       |
| `upload_adjustment_file`              | Uploads an xlsx to S3 and triggers the Airflow validation + import pipeline  |
| `submit_adjustment_batch`             | Submits Claude-generated adjustment rows as a batch via the JSON lambda path |
| `get_adjustment_batch_status`         | Returns the current status of an adjustment batch                            |
| `get_adjustment_template`             | Returns a presigned download URL for the canonical adjustment Excel template |

## Runner tools (conditional)

Source: **Runner service** — requires `@coda/runner-api` (`RUNNER_SERVICE_URL` env var)

| Tool                 | What it does                                                             |
| -------------------- | ------------------------------------------------------------------------ |
| `execute_code`       | Execute JavaScript/TypeScript in a sandboxed V8 isolate with data bridge |
| `refresh_datasource` | Trigger an async datasource refresh (enqueues to SQS)                    |
| `get_refresh_status` | Check the status of a datasource refresh job                             |