Skip to main content
Glama

Search companies

search_companies
Destructive

Use this when the user wants to find companies: by a plain-language description, by filters, or by a saved company search. Send exactly one of query, filters, savedSearchId or savedSearchName. Returns one page of companies with their names, domains, industries, number of employees, funding stage and location, and the filters the search ran with; for the next page, send those filters with the page's next cursor. It lists companies, not the people who work at them. Costs $0.001 per company returned, charged to the organization's balance; an empty page is free. Calling again with the same arguments charges again.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "search_companies"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoCompanies per page. The page's most possible cost, `limit` times $0.001, is held from your balance first.
queryNoWhich companies to find, in plain language. It is turned into filters, which the page answers with as `filters`.
cursorNoThe `pagination.nextCursor` of the page before. Send it with the same search, as the `filters` the first page answered with.
filtersNoFilters by name. Each filter's allowed values are listed with the company filters and are case-sensitive; company names and headquarters places take a suggested value.
savedSearchIdNoRun a saved company search by its id.
savedSearchNameNoRun a saved company search by its title. A title several saved searches share answers 409 `saved_search_name_ambiguous`.

Schema Changelog

Changes observed during successful MCP inspections.

No schema history has been recorded yet.

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag non-read-only, non-idempotent, destructive and open-world, and the description supplies the concrete reason: $0.001 per company, a balance hold of limit × $0.001, empty pages free, and repeat calls with identical arguments charging again. That cost/idempotency disclosure is exactly the missing context an agent needs. It stops short of explaining the openWorldHint or how a search could be destructive to any data, so it is strong but not exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Trigger, invocation rule, return shape, scope boundary and cost model each get one tight sentence, ordered so the most decision-critical facts come first. No boilerplate or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter, nested-filter, metered search with no output schema to lean on, the description still names the returned fields, explains pagination mechanics and pricing, and warns about ambiguous saved-search names — nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage the baseline is 3, but the description adds real semantics: the four search modes are mutually exclusive, query is compiled into filters that come back on the page, and the cursor must be re-sent alongside those same filters for pagination to work. Those are relationships the schema documents only per-field.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (find/search) and resource (companies), enumerates the three input modes, and explicitly bounds the scope with 'it lists companies, not the people who work at them', which separates it from search_people without needing a schema lookup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Opens with a direct trigger ('Use this when the user wants to find companies') and adds a hard invocation rule — send exactly one of query, filters, savedSearchId or savedSearchName — plus an exclusion that routes people-searches elsewhere.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources