Skip to main content
Glama

Filter companies (portfolio / market sizing)

advanced_search
Read-onlyIdempotent

Filter companies by country, NACE, status, region, turnover, employees, founding date, VAT payer, tax debt, or sanctions to build portfolios and size markets; paged results include match counts.

Instructions

Structured company search for portfolio building and market sizing — NOT for finding one known company (use search_companies). Filters: country, NACE prefix, status, region, turnover range (EUR), employee range, founding date range, VAT payer, tax debt, sanctions. Results are paged (limit + offset); the response says how many matched. Only the listed arguments exist — anything else is rejected, never silently ignored.

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": "advanced_search"
  }
}

Input Schema

NameRequiredDescriptionDefault
naceNoNACE code prefix, dotted or not: division '62' (IT services, same across all markets), group '62.0' / '620', class '62.01' / '6201'. Classes are national: SK, AT, SE, SI, BE, GR and LT store NACE Rev. 2.1 since 2025, so a class filter also matches the other revision's equivalent class (62.01 also finds Rev. 2.1 62.10). An invalid code is rejected with an error, never ignored.
limitNoPage size (default 50).
orderNoSort order (default turnover_desc).
offsetNoRows to skip for the next page.
regionNoRegion name exactly as the register spells it.
statusNoCompany lifecycle status.
countryNoISO 3166-1 alpha-2 country of the register (e.g. SK, CZ, AT, PL). Strongly recommended: registry numbers are NOT unique across countries (an SK and a CZ company can share the same 8-digit IČO), and without it the server picks one by tie-break.
tax_debtNoOnly companies on (true) / off (false) the tax-debtor list.
vat_payerNoOnly VAT-registered (true) or only non-registered (false).
founded_toNoFounded on or before (YYYY-MM-DD).
sanctionedNoOnly companies with (true) / without (false) a sanctions hit.
founded_fromNoFounded on or after (YYYY-MM-DD).
employees_maxNoMaximum number of employees.
employees_minNoMinimum number of employees.
turnover_max_eurNoMaximum latest annual turnover in EUR.
turnover_min_eurNoMinimum latest annual turnover in EUR.

Output Schema

NameRequiredDescriptionDefault
dataNoMatching companies for this page, plus total count and any unknownFilters.
metaNoRequest metadata: request_id (quote it in support requests), duration_ms, cached.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed74 schema fields changedv0.2.2
    • removedInput schema / $schema
      Removed value: -"http://json-schema.org/draft-07/schema#"
    • removedInput schema / properties / active
      Removed value: -{
      -  "description": "Registry active flag (NOT is_active)",
      -  "type": "boolean"
      -}
    • removedInput schema / properties / contracts_min
      Removed value: -{
      -  "description": "Minimum contract count",
      -  "type": "integer"
      -}
    • changedInput schema / properties / country / description
      Previous value: -"Alias for country_code. ISO 3166-1 alpha-2, e.g. 'SK'."New value: +"ISO 3166-1 alpha-2 country of the register (e.g. SK, CZ, AT, PL). Strongly recommended: registry numbers are NOT unique across countries (an SK and a CZ company can share the same 8-digit IČO), and without it the server picks one by tie-break."
    • addedInput schema / properties / country / pattern
      Added value: +"^[A-Za-z]{2}$"
    • removedInput schema / properties / country_code
      Removed value: -{
      -  "description": "ISO 3166-1 alpha-2, comma-separated for several markets, e.g. 'SK,CZ'",
      -  "type": "string"
      -}
    • removedInput schema / properties / credit_grade
      Removed value: -{
      -  "description": "Comma-separated grade letters, e.g. 'A,B'",
      -  "type": "string"
      -}
    • removedInput schema / properties / credit_score_max
      Removed value: -{
      -  "type": "integer"
      -}
    • removedInput schema / properties / credit_score_min
      Removed value: -{
      -  "type": "integer"
      -}
    • removedInput schema / properties / cyber_score_min
      Removed value: -{
      -  "type": "integer"
      -}
    • removedInput schema / properties / district
      Removed value: -{
      -  "type": "string"
      -}
    • removedInput schema / properties / employee_max
      Removed value: -{
      -  "description": "Maximum headcount (NOT employees_max)",
      -  "type": "integer"
      -}
    • removedInput schema / properties / employee_min
      Removed value: -{
      -  "description": "Minimum headcount (NOT employees_min)",
      -  "type": "integer"
      -}
    • removedInput schema / properties / employee_size
      Removed value: -{
      -  "description": "Employee size-band code",
      -  "type": "string"
      -}
    • addedInput schema / properties / employees_max
      Added value: +{
      +  "description": "Maximum number of employees.",
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedInput schema / properties / employees_min
      Added value: +{
      +  "description": "Minimum number of employees.",
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • removedInput schema / properties / entity_type
      Removed value: -{
      -  "description": "Comma-separated also accepted. Natural persons are gated out of results anyway.",
      -  "enum": [
      -    "legal_entity",
      -    "self_employed",
      -    "npo",
      -    "public_body",
      -    "other"
      -  ],
      -  "type": "string"
      -}
    • removedInput schema / properties / established_from
      Removed value: -{
      -  "description": "Founded on or after, ISO date YYYY-MM-DD",
      -  "type": "string"
      -}
    • removedInput schema / properties / established_to
      Removed value: -{
      -  "description": "Founded on or before, ISO date YYYY-MM-DD",
      -  "type": "string"
      -}
    • removedInput schema / properties / eu_funds_min
      Removed value: -{
      -  "description": "Minimum EU funds received, EUR",
      -  "type": "number"
      -}
    • addedInput schema / properties / founded_from
      Added value: +{
      +  "description": "Founded on or after (YYYY-MM-DD).",
      +  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      +  "type": "string"
      +}
    • addedInput schema / properties / founded_to
      Added value: +{
      +  "description": "Founded on or before (YYYY-MM-DD).",
      +  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      +  "type": "string"
      +}
    • removedInput schema / properties / has_contracts
      Removed value: -{
      -  "description": "Has public procurement contracts",
      -  "type": "boolean"
      -}
    • removedInput schema / properties / has_critical_cves
      Removed value: -{
      -  "type": "boolean"
      -}
    • removedInput schema / properties / has_cves
      Removed value: -{
      -  "type": "boolean"
      -}
    • removedInput schema / properties / has_email
      Removed value: -{
      -  "type": "boolean"
      -}
    • removedInput schema / properties / has_financials
      Removed value: -{
      -  "type": "boolean"
      -}
    • removedInput schema / properties / has_offshore_link
      Removed value: -{
      -  "type": "boolean"
      -}
    • removedInput schema / properties / has_phone
      Removed value: -{
      -  "type": "boolean"
      -}
    • removedInput schema / properties / has_rpvs
      Removed value: -{
      -  "description": "SK register of public-sector partners",
      -  "type": "boolean"
      -}
    • removedInput schema / properties / has_tax_debt
      Removed value: -{
      -  "type": "boolean"
      -}
    • removedInput schema / properties / has_tech
      Removed value: -{
      -  "description": "Any detected technology at all",
      -  "type": "boolean"
      -}
    • removedInput schema / properties / has_website
      Removed value: -{
      -  "type": "boolean"
      -}
    • removedInput schema / properties / healthy
      Removed value: -{
      -  "description": "Shorthand: no bankruptcy, liquidation, restructuring or tax debt",
      -  "type": "boolean"
      -}
    • removedInput schema / properties / in_bankruptcy
      Removed value: -{
      -  "type": "boolean"
      -}
    • removedInput schema / properties / in_liquidation
      Removed value: -{
      -  "type": "boolean"
      -}
    • removedInput schema / properties / in_restructuring
      Removed value: -{
      -  "type": "boolean"
      -}
    • removedInput schema / properties / is_debarred
      Removed value: -{
      -  "description": "Excluded from public procurement",
      -  "type": "boolean"
      -}
    • removedInput schema / properties / is_sanctioned
      Removed value: -{
      -  "description": "NOT 'sanctioned'",
      -  "type": "boolean"
      -}
    • removedInput schema / properties / is_vat_payer
      Removed value: -{
      -  "type": "boolean"
      -}
    • removedInput schema / properties / legal_form
      Removed value: -{
      -  "description": "Legal form code, e.g. '112' = s.r.o. (SK)",
      -  "type": "string"
      -}
    • changedInput schema / properties / limit / description
      Previous value: -"Max results (default 50, cap 200)"New value: +"Page size (default 50)."
    • removedInput schema / properties / municipality
      Removed value: -{
      -  "description": "Town/city name, e.g. 'Košice'",
      -  "type": "string"
      -}
    • changedInput schema / properties / nace / description
      Previous value: -"Single NACE prefix match, e.g. '46'"New value: +"NACE code prefix, dotted or not: division '62' (IT services, same across all markets), group '62.0' / '620', class '62.01' / '6201'. Classes are national: SK, AT, SE, SI, BE, GR and LT store NACE Rev. 2.1 since 2025, so a class filter also matches the other revision's equivalent class (62.01 also finds Rev. 2.1 62.10). An invalid code is rejected with an error, never ignored."
    • addedInput schema / properties / nace / pattern
      Added value: +"^[0-9]{2}(\\.?[0-9]{1,4})?$"
    • removedInput schema / properties / nace_prefix
      Removed value: -{
      -  "description": "Comma-separated NACE prefixes, e.g. '46,47'",
      -  "type": "string"
      -}
    • removedInput schema / properties / nis2_in_scope
      Removed value: -{
      -  "description": "NOT 'nis2_scope'",
      -  "type": "boolean"
      -}
    • removedInput schema / properties / nis2_sector
      Removed value: -{
      -  "type": "string"
      -}
    • removedInput schema / properties / nis2_tier
      Removed value: -{
      -  "description": "essential | important",
      -  "type": "string"
      -}
    • removedInput schema / properties / nuts2
      Removed value: -{
      -  "description": "NUTS-2 code",
      -  "type": "string"
      -}
    • removedInput schema / properties / nuts3
      Removed value: -{
      -  "description": "NUTS-3 code, e.g. 'SK042'",
      -  "type": "string"
      -}
    • changedInput schema / properties / offset / description
      Previous value: -"Pagination offset"New value: +"Rows to skip for the next page."
    • addedInput schema / properties / offset / maximum
      Added value: +10000
    • changedInput schema / properties / order / description
      Previous value: -"NOT 'sort'. An unrecognised value falls back to turnover_desc silently."New value: +"Sort order (default turnover_desc)."
    • changedInput schema / properties / order / enum
      Previous value: -[
      -  "turnover_desc",
      -  "turnover_asc",
      -  "profit_desc",
      -  "name_asc",
      -  "contracts_desc",
      -  "nis2_priority_desc",
      -  "credit_score_desc"
      -]New value: +[
      +  "turnover_desc",
      +  "turnover_asc",
      +  "profit_desc",
      +  "name_asc",
      +  "contracts_desc",
      +  "credit_score_desc"
      +]
    • removedInput schema / properties / profit_max
      Removed value: -{
      -  "description": "Maximum annual profit in EUR",
      -  "type": "number"
      -}
    • removedInput schema / properties / profit_min
      Removed value: -{
      -  "description": "Minimum annual profit in EUR",
      -  "type": "number"
      -}
    • changedInput schema / properties / region / description
      Previous value: -"Region NAME only, e.g. 'Košický kraj'. A NUTS code here returns zero — use nuts3."New value: +"Region name exactly as the register spells it."
    • addedInput schema / properties / region / maxLength
      Added value: +100
    • addedInput schema / properties / sanctioned
      Added value: +{
      +  "description": "Only companies with (true) / without (false) a sanctions hit.",
      +  "type": "boolean"
      +}
    • removedInput schema / properties / ssl_invalid
      Removed value: -{
      -  "type": "boolean"
      -}
    • addedInput schema / properties / status / description
      Added value: +"Company lifecycle status."
    • addedInput schema / properties / tax_debt
      Added value: +{
      +  "description": "Only companies on (true) / off (false) the tax-debtor list.",
      +  "type": "boolean"
      +}
    • removedInput schema / properties / tech
      Removed value: -{
      -  "description": "Named technology, exact match, e.g. 'PrestaShop', 'Shoptet', 'CookieYes'. An unknown name returns 400 with the full list in meta.available — ask for a wrong one once to discover what is detectable.",
      -  "type": "string"
      -}
    • removedInput schema / properties / terminated_from
      Removed value: -{
      -  "description": "Terminated on or after, ISO date",
      -  "type": "string"
      -}
    • removedInput schema / properties / terminated_to
      Removed value: -{
      -  "description": "Terminated on or before, ISO date",
      -  "type": "string"
      -}
    • removedInput schema / properties / turnover_max
      Removed value: -{
      -  "description": "Maximum annual turnover in EUR",
      -  "type": "number"
      -}
    • addedInput schema / properties / turnover_max_eur
      Added value: +{
      +  "description": "Maximum latest annual turnover in EUR.",
      +  "minimum": 0,
      +  "type": "number"
      +}
    • removedInput schema / properties / turnover_min
      Removed value: -{
      -  "description": "Minimum annual turnover in EUR",
      -  "type": "number"
      -}
    • addedInput schema / properties / turnover_min_eur
      Added value: +{
      +  "description": "Minimum latest annual turnover in EUR.",
      +  "minimum": 0,
      +  "type": "number"
      +}
    • removedInput schema / properties / updated_since
      Removed value: -{
      -  "description": "Only rows changed since this ISO date",
      -  "type": "string"
      -}
    • addedInput schema / properties / vat_payer
      Added value: +{
      +  "description": "Only VAT-registered (true) or only non-registered (false).",
      +  "type": "boolean"
      +}
    • removedInput schema / properties / year
      Removed value: -{
      -  "description": "Financial year for period-specific figures",
      -  "type": "integer"
      -}
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "properties": {
      +    "data": {
      +      "description": "Matching companies for this page, plus total count and any unknownFilters."
      +    },
      +    "meta": {
      +      "description": "Request metadata: request_id (quote it in support requests), duration_ms, cached.",
      +      "type": "object"
      +    }
      +  },
      +  "type": "object"
      +}
  2. Changed1 schema field changedv0.1.4
    • addedInput schema / properties / country
      Added value: +{
      +  "description": "Alias for country_code. ISO 3166-1 alpha-2, e.g. 'SK'.",
      +  "type": "string"
      +}
  3. First observedv0.1.0

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description adds genuinely new behavior: results are paged via limit+offset, the response reports the match count, and unknown arguments are hard-rejected rather than silently ignored (consistent with additionalProperties=false). It stops short of noting result caps or what happens past the offset maximum, so it is not fully exhaustive.

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

Conciseness4/5

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

Front-loads the routing decision and the negative case in the first sentence, then compresses paging and error behavior into two short clauses. The middle filter enumeration is partly redundant with the schema but is cheap to scan and aids quick capability matching.

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?

An output schema exists, so return-value structure need not be described; the description still usefully notes paging mechanics and that a match count comes back. For a 16-parameter, all-optional filter tool with full schema coverage and annotations, nothing an agent needs to call it correctly is missing.

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

Parameters3/5

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

Schema description coverage is 100%, so every one of the 16 parameters is already documented with format, ranges, and constraints in the schema. The description's filter enumeration (country, NACE prefix, status, turnover/employee ranges, etc.) largely restates what the schema already provides, adding no syntax or default detail beyond it. Baseline 3 applies when the schema does the heavy lifting.

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 and resource ('Structured company search') plus the intended job ('portfolio building and market sizing'), and explicitly names the sibling it is not for ('use search_companies' for one known company). An agent can route between advanced_search and search_companies without opening either schema.

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?

Gives both a when-to-use condition (bulk filtering for portfolio/market sizing) and an explicit when-not with the alternative tool named (finding one known company -> search_companies). The filter list also signals the intended query shape.

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