Symbol search
Resolve company names, tickers, or ISINs to canonical tradeable symbols before placing orders or pulling data.
The symbol_search tool resolves ambiguous identifiers — company names, partial tickers, ISINs, or CUSIPs — to the canonical symbols used by your configured venues and data providers.
Why resolution matters
Market identifiers are not universal. A company may trade on multiple venues under different tickers, have share classes with distinct symbols, or be known colloquially by a name that does not match any ticker. Submitting an order against an unresolved or ambiguous identifier is a common source of errors.
The symbol_search tool queries your configured data provider's symbol directory, returns a ranked list of candidates with their venue listings and instrument types, and lets the agent (or you) select the correct one before any data pull or order is attempted.
Disambiguation
When a query matches multiple candidates, the tool returns all matches ranked by relevance. The agent presents the list and asks you to confirm the intended symbol if there is meaningful ambiguity — for example, if a name matches both a common stock and a preferred share class, or a domestic and a foreign-listed ADR.
Once resolved, the canonical symbol is stored in the entity file for that name (entities/<slug>.toml) so future queries do not need to re-resolve it. The entity file also records the venue(s) on which the symbol is listed.
Tool call and result
// Tool call (agent → MCP server)
{
"tool": "symbol_search",
"input": {
"query": "semiconductor ETF broad market",
"limit": 5,
"instrument_types": ["etf"]
}
}
// Tool result (MCP server → agent)
{
"results": [
{
"symbol": "SOXX",
"name": "iShares Semiconductor ETF",
"instrument_type": "etf",
"venues": ["equities-primary"],
"isin": "US46429B2022",
"relevance_score": 0.94
},
{
"symbol": "SMH",
"name": "VanEck Semiconductor ETF",
"instrument_type": "etf",
"venues": ["equities-primary"],
"isin": "US92189H5006",
"relevance_score": 0.91
},
{
"symbol": "SOXQ",
"name": "Invesco PHLX Semiconductor ETF",
"instrument_type": "etf",
"venues": ["equities-primary"],
"isin": "US46138G6476",
"relevance_score": 0.87
}
],
"query_id": "sqr_20260705_0041"
}ISIN and CUSIP lookups
You can pass an ISIN or CUSIP directly as the query string. The tool detects the format automatically and performs an exact-match lookup before falling back to text search. This is the most reliable way to resolve a specific instrument when the identifier is known.
symbol_search input parameters
| Parameter | Type | Description |
|---|---|---|
query | string (required) | Name, ticker fragment, ISIN, or CUSIP to search for. |
limit | integer (default 10) | Maximum number of candidates to return. |
instrument_types | string[] (optional) | Filter by type: equity, etf, index, future, option. |
venues | string[] (optional) | Restrict results to symbols listed on specified venue IDs. |
country | string (optional) | ISO 3166-1 alpha-2 country code to narrow the search. |
Saving resolved symbols to entities
After confirming a symbol, the agent writes or updates the corresponding entity file at entities/<slug>.toml. The file stores the canonical symbol, the ISIN, and the venue listing so that all subsequent data pulls for that entity use the correct identifier without re-querying.
You can also pre-populate entity files manually. If the agent finds an entity file with a symbol field already set, it skips the resolution step entirely and uses that symbol directly.
Ask the agent to resolve a symbol before researching
If you are starting research on a company you have not tracked before, open your agent session and ask it to 'find the symbol for <name> and add it to entities'. This primes the workspace so every subsequent data pull and order proposal uses the right identifier.