The MCP server exposes eight tools. All eight are read-only. When a client connects, it discovers them automatically via MCP's tools/list — there is no separate REST surface to learn.

The same server also exposes this documentation as MCP resources. A client can list them via resources/list and fetch the raw Markdown via resources/read, with URIs like https://mcp.goi.istari.ai/docs/tools.md. Pick whichever discovery path your client supports.

A successful tool call returns a Markdown-formatted response. On errors, the response is a string beginning with Error: followed by a human-readable explanation. Every successful response (above an 80% quota threshold) gets a footer disclosing your active scope and remaining monthly budget.

search_organizations¶

Search the GOI corpus with auto-detected mode:

• query alone → semantic (embedding) search.
• keywords_* alone → BM25 full-text search.
• query + keywords_* → hybrid with Reciprocal Rank Fusion.

Add filters (country, state, NACE sector, organization size / type, register attributes, summary keyword tags) to narrow the scope. Results are deduplicated by name and paginated with an opaque search_after cursor.

Use this for "find me companies that …" and exploratory market research questions.

find_similar_organizations¶

Find companies similar to up to three reference domains via embedding similarity. Optional keywords_must_all / keywords_must_not are applied as post-filters.

If a reference domain is not already in GOI, the public site is fetched and embedded on demand. The resulting embedding is cached across users — see Privacy.

Use for "companies like X" — competitive benchmarking, supplier discovery, peer-group analysis.

find_similar_with_steering¶

Same as find_similar_organizations but with embedding arithmetic to steer the search:

• boost — up to five terms whose averaged embedding is added to the reference vector. Pulls the search toward a concept.
• penalize — up to five terms whose embedding is subtracted. Pushes the search away.
• repel_domains — up to five domains whose embeddings are subtracted. Pushes the search away from a specific company.
• weight — weak (0.5), normal (1.0), or strong (2.0) to scale every adjustment.

Use this when a plain similarity search returns too much of the wrong thing — for example "companies like Stripe, but enterprise-focused" maps to domains=["stripe.com"], boost=["enterprise"].

filter_organizations¶

Enumerate companies matching structured criteria, with no relevance scoring. Supports the same filter dimensions as search_organizations, plus optional keyword filters that trigger a BM25 query. Useful when you know exactly what you want and don't need ranking.

get_organization_details¶

Fetch full company profiles by exact domain. Up to 20 domains per call. Returns identity, location, classification (NACE, type, size), description, keywords, and registry filings for each.

Use this after a search to drill into specific companies, or when you already have a list of domains to look up.

aggregate_organizations¶

Count companies grouped by one or two dimensions, optionally with a date bucket. Supports the full set of filterable dimensions plus continent, country_code, state_code, region_code, district_code, municipality_code, employee_class, revenue_class, source, summary_keywords, company_register_date, and created_at.

Use for "how many", "share of", "distribution of", and "trend of" questions. Returns a table the caller can chart directly.

describe_filters¶

Returns valid values for the enumerable filter columns (organization_size, organization_type, nace_code, company_register_court), plus a documentation block describing the date-filter parameters and how to resolve location names.

Call this once at the start of a session to ground filter-string choices, instead of guessing.

resolve_location¶

Fuzzy-match a free-text place name to the canonical GADM administrative entry. Returns ranked candidates with their admin level (country / state / region / district / municipality) and a suggested filter object to drop into the next call.

Place names follow GADM's native official spelling — Bayern not Bavaria, München not Munich, Île-de-France not Ile de France. The fuzzy match catches anglicizations and minor misspellings, but the value returned to filters is the canonical form.

Filter dimensions¶

All filter-accepting tools (search_organizations, find_similar_*, filter_organizations, aggregate_organizations) share the same filter parameter set:

Values within a single field combine with OR. Different fields combine with AND. See the GOI dashboard docs for the same filters as they appear in the web UI.

A note on commercial-register data¶

The registry fields (company_register_court, register_date_*) are populated only for German, Austrian, and Swiss companies today, and only for entries appearing in the commercial register from January 2026 onwards. Companies outside that scope have null register attributes and are excluded from any filter on those fields. The rest of the dataset (~20M companies across 232 countries) is unaffected.

This isn't an API restriction — it's the current state of the underlying source data. Coverage expands over time.

Pagination¶

Search and filter tools return up to 500 results per call, default 20. The response includes an opaque search_after cursor; pass it verbatim on the next call to get the next page.

Errors¶

Tool errors are returned as plain text in the format:

Error [<CODE>]: <human-readable message>

The bracketed code is stable across releases and lets a client (or LLM) route on a single identifier instead of parsing prose. The message body explains what specifically went wrong and what to do.

INTERNAL errors are the only ones whose detail is intentionally opaque — full traceback goes to our server logs, not to you.