> For the complete documentation index, see [llms.txt](https://docs.orbitfin.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.orbitfin.ai/orbit-api-reference/mcp/2.3-orbit-agent-builder-tools.md).

# 2.3 Orbit Agent Builder Tools

### Agent Builder Workflow Tools 

*This feature is currently free for a limited time.*

You can read "User Guide" to understand the usage workflow of this tool.

> The Agent Builder project offers a relatively large number of general-purpose tools and supports both creating and using them. For this reason, we provide a dedicated URL to make it easier to combine and use these tools. The URL is as follows:

<https://mcp.orbitfin.ai/agentbuilder/mcp><br>

<table><thead><tr><th width="194.1484375">Tool Name</th><th width="244.72265625">Description</th><th width="96.1015625">Credit</th><th>Note</th></tr></thead><tbody><tr><td>Portfolio List</td><td>Read-only, lists the user's existing portfolios as analysis targets</td><td>Free</td><td>Default limit 20, max 50; portfolios managed elsewhere</td></tr><tr><td>Ag Workflow Status</td><td>Read-only snapshot of the current Agent Builder workflow state</td><td>Free</td><td>Pure status check, never mutates draft/agent</td></tr><tr><td>Ag Continue</td><td>Read-only advisory navigator suggesting the next tool for vague user<br>requests</td><td>Free</td><td>Never executes the suggested action itself</td></tr><tr><td>Ag Config Build</td><td>Creates a brand-new Agent draft from a natural-language requirement</td><td>Free</td><td>Blocked if an active draft already exists</td></tr><tr><td>Ag Config Load</td><td>Read-only, reviews the current active draft</td><td>Free</td><td>Returns human-readable config; hides raw ids</td></tr><tr><td>Ag Config Discard</td><td>Discards the current draft</td><td>Free</td><td>Only for explicit user request; doesn't delete saved Agents</td></tr><tr><td>Ag Config Set Target</td><td>Sets/replaces the draft's target company</td><td>Free</td><td>ids must come from a prior company_search result</td></tr><tr><td>Ag Config Edit</td><td>Edits the draft's data sources / time window / cadence / extraction<br>fields</td><td>Free</td><td>Only editable before Agent creation starts</td></tr><tr><td>Ag Generate Start</td><td>Starts creating an Agent from the approved draft</td><td>Free</td><td>Marks creation "started", not "finished"</td></tr><tr><td>Ag Generate Status</td><td>Read-only, checks whether Agent creation has finished</td><td>Free</td><td>agent_ref resolves by name/company if id unknown</td></tr><tr><td>Ag Analyze List</td><td>Read-only, lists saved Agents for the user to choose from</td><td>Free</td><td>Default limit 3, max 20</td></tr><tr><td>Ag Analyze Start</td><td>Starts a final analysis run for a chosen saved Agent</td><td>Free</td><td>force=false dedupes recent runs by default</td></tr><tr><td>Ag Analyze Result</td><td>Read-only, checks analysis progress or fetches report/structured<br>results</td><td>Free</td><td>Default limit 5, offset 0</td></tr><tr><td>Ag Agent List</td><td><p>Lists the current user's active saved Agent Builder Agents from the database,</p><p>so the user can choose one to run analysis</p></td><td>Free</td><td>Default limit 50, max 100;</td></tr></tbody></table>

### User Guide

> Audience: end users creating a "persistent tracking Agent" through a Copilot / Claude / ChatGPT conversation. You don't need to know any tool names or parameters — just talk to your assistant in plain language.

### 1. What this feature does

Agent Builder helps you create a "persistent tracking" analysis assistant (an Agent). Describe, in one sentence, which company/portfolio you want to track and what you care about, and your assistant (Copilot / Claude / ChatGPT) will:

1. Generate a draft tracking plan (what data to track, how often to update, which metrics to watch)
2. Let you confirm or adjust that plan
3. Formally create the Agent
4. Run analysis manually, whenever you ask (scheduled auto-runs aren't supported yet — see the FAQ below)
5. Produce a report you can check any time

### 2. How to get started

Just tell your assistant what you want to track, for example:

* "Build me an assistant tracking Apple's cash flow health"
* "I want a weekly update on NVIDIA's competitiveness in AI chips"
* "Set up a monthly risk tracker for my 'Semiconductors' portfolio"

Your assistant will show you a draft plan that includes:

* Tracking target (a company, or an existing portfolio)
* Data sources (filings, news, stock price, etc.)
* Update frequency (daily / weekly / monthly / on demand — currently just recorded in the plan and doesn't trigger auto-runs yet, see the FAQ below)
* Specific metrics to watch

### 3. Reviewing and adjusting the plan

Once the draft is shown, you can:

* **Approve it as-is**: "Looks good, create it" / "That works"
* **Ask for changes**: "Change the cadence to weekly" / "Add ESG tracking" / "Switch to the portfolio instead of a single company"
* **Start over**: "Never mind, let's redo this"

Once you approve and the Agent is created, the plan can no longer be edited — if you need a different setup later, you'll create a new Agent.

### 4. Creating and running

After you approve the plan:

* Your assistant will say it's "creating" — you can ask "is it ready yet?" anytime
* Once creation is done, say "run the analysis" to start a run
* If you have multiple saved assistants, you can refer to one by name ("the NVIDIA one I set up before") or ask it to "list the assistants I've built"

### 5. Viewing results

Once analysis is done, just ask "is the result ready?" or "show me the report" and your assistant will give you:

* A viewable analysis report
* Or a structured summary of the key data

If the analysis is still running, it will tell you roughly how far along it is.

### 6. FAQ

**Q: Can one assistant track multiple companies?** Yes — if you choose a portfolio instead of a single company, the assistant tracks every company in it.

**Q: I want to change the tracking frequency after creation — can I?** No, the configuration is locked once the Agent is created. You'll need to build a new one for a different setup.

**Q: Does the assistant run automatically on a schedule?** Not yet — every analysis run currently has to be triggered manually by asking "run the analysis." The frequency you set in the plan is only recorded for reference and doesn't auto-trigger anything right now. Scheduled auto-runs need to be configured separately on the Insight platform. This is intentional: there isn't yet a visible run-history view here, so if auto-scheduling were enabled by default, a run could keep consuming credits without anyone noticing.

**Q: I can't remember which assistants I've already built — what do I do?** Just ask "what assistants have I built?" and it'll list them for you to choose from.

### Tool Reference (Internal / Developer Doc)

> Audience: prompt engineers / client developers integrating this MCP — not end users.
>
> These tools are currently free/promotional (no billing).

### 1. Workflow state model

Draft → Agent (after creation) → Analysis run are three progressive states; tools are grouped by\
which state they operate on.

### 2. Tool list (grouped by workflow stage)

#### 2.1 Navigation / status (read-only)

| Tool Name                               | When to use                                                                                                          |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| ag\_workflow\_status Ag Workflow Status | Low-level lookup when you need to know exactly which state the workflow is in                                        |
| ag\_continue Ag Continue                | When the user gives a vague instruction ("continue", "OK", "what now"), ask this first for the recommended next tool |

#### 2.2 Draft management

| Tool Name                                    | When to use                                                                 |
| -------------------------------------------- | --------------------------------------------------------------------------- |
| ag\_config\_build Ag Config Build            | Create a brand-new draft from scratch (no active draft exists)              |
| ag\_config\_load Ag Config Load              | Review the current draft's full configuration                               |
| ag\_config\_set\_target Ag Config Set Target | Change only the draft's target company                                      |
| ag\_config\_edit Ag Config Edit              | Change the draft's data sources / time window / cadence / extraction fields |
| ag\_config\_discard Ag Config Discard        | The user explicitly wants to abandon the current draft                      |

#### 2.3 Agent creation

| Tool Name                               | When to use                                                        |
| --------------------------------------- | ------------------------------------------------------------------ |
| ag\_generate\_start Ag Generate Start   | User approved the draft — formally start Agent creation            |
| ag\_generate\_status Ag Generate Status | Check whether creation has finished ("ready" vs. "still creating") |

#### 2.4 Selecting a target / saved Agent

| Tool Name                         | When to use                                               |
| --------------------------------- | --------------------------------------------------------- |
| ag\_analyze\_list Ag Analyze List | List the user's saved Agents for selection                |
| portfolio\_list Portfolio List    | List the user's existing portfolios as an analysis target |

#### 2.5 Run analysis / fetch results

| Tool Name                             | When to use                                                   |
| ------------------------------------- | ------------------------------------------------------------- |
| ag\_analyze\_start Ag Analyze Start   | Start an analysis run for an already-created Agent            |
| ag\_analyze\_result Ag Analyze Result | Check run progress, or fetch the report URL / structured data |

### 3. Typical conversation flow (happy path, with actual tool calls)

```
User: "Build me an Agent tracking NVIDIA's competitiveness in AI chips"
  → ag_config_build(requirement=..., orbit_entity_ids=None)
      (if the entity_id is unknown, resolve it via company_search first)

Assistant shows the draft. User: "Change the cadence to weekly"
  → ag_config_edit(ag_id=..., schedule="Weekly")

User: "Looks good, create it"
  → ag_generate_start()

Assistant: "Creating — checking status shortly"
  → ag_generate_status()  (poll until ready)

User: "Run the analysis"
  → ag_analyze_start(ag_id=...)

User: "Is the result ready?"
  → ag_analyze_result(ag_id=..., agent_type="report")
```

Whenever the user's instruction is vague ("continue", "what now", "check progress"), call `ag_continue` first for the recommended next step instead of guessing.

### 4. Key constraints / notes

* **Never expose internal ids to the user**: `ag_id`, `dag_run_id`, etc. are tool-to-tool arguments only — always refer to the company/Agent name in user-facing replies.
* **A draft is only editable before Agent creation starts**: once `ag_generate_start` succeeds, the config is frozen and `ag_config_edit` no longer applies.
* **Target company ids must come from a company\_search result**: never pass a guessed name/ticker directly to `ag_config_set_target` / `ag_config_build`.
* **Dedup by default**: `ag_analyze_start` defaults to `force=False`, which skips re-triggering if a recent run already exists — only pass `force=True` when the user explicitly asks to re-run.
* **Fuzzy reference resolution**: several tools accept `agent_ref` (a natural-language reference, e.g. "the NVIDIA one"). If resolution fails or matches multiple candidates, the tool returns a "needs user selection" response — never guess on the model's behalf.