Skip to main content
Glama

List companies

list_companies
Read-onlyIdempotent

Find covered companies and their tickers, latest quarter and next expected report date, sorted by name. Filter by query (name, ticker, sector, country or exchange words), sector or country. Pages of 50 by default (up to 200); total and next_offset tell you whether there are more. Unknown sectors or countries return an error that lists the valid ones.

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

Input Schema

NameRequiredDescriptionDefault
limitNoNumber of companies, 1-200, default 50
queryNoWords in the name, ticker, sector, country or exchange, such as 'bank singapore' or 'Barclays'
offsetNoWhere to start, default 0; pass next_offset from the previous page
sectorNoSector, such as Banking, Insurance, Semiconductors or Software; loose matches work ('Banks')
countryNoHome country, such as United States, Singapore or United Kingdom

Output Schema

NameRequiredDescriptionDefault
noteNo
totalYes
offsetYes
resultsYes
next_offsetNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed14 schema fields changed
    • addedInput schema / additionalProperties
      Added value: +false
    • addedInput schema / properties / country
      Added value: +{
      +  "description": "Home country, such as United States, Singapore or United Kingdom",
      +  "maxLength": 60,
      +  "type": "string"
      +}
    • addedInput schema / properties / limit
      Added value: +{
      +  "description": "Number of companies, 1-200, default 50",
      +  "maximum": 200,
      +  "minimum": 1,
      +  "type": "integer"
      +}
    • addedInput schema / properties / offset
      Added value: +{
      +  "description": "Where to start, default 0; pass next_offset from the previous page",
      +  "maximum": 9007199254740991,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedInput schema / properties / query
      Added value: +{
      +  "description": "Words in the name, ticker, sector, country or exchange, such as 'bank singapore' or 'Barclays'",
      +  "maxLength": 80,
      +  "type": "string"
      +}
    • changedInput schema / properties / sector / description
      Previous value: -"Such as Semiconductors or Software"New value: +"Sector, such as Banking, Insurance, Semiconductors or Software; loose matches work ('Banks')"
    • addedInput schema / properties / sector / maxLength
      Added value: +60
    • addedOutput schema / properties / next_offset
      Added value: +{
      +  "type": [
      +    "number",
      +    "null"
      +  ]
      +}
    • addedOutput schema / properties / note
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / offset
      Added value: +{
      +  "type": "number"
      +}
    • addedOutput schema / properties / results / items / properties / country
      Added value: +{
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • addedOutput schema / properties / results / items / properties / currency
      Added value: +{
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • addedOutput schema / properties / total
      Added value: +{
      +  "type": "number"
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "results"
      -]New value: +[
      +  "results",
      +  "total",
      +  "offset"
      +]
  2. First observed

TDQS

A4/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent and non-destructive, so safety is covered. The description adds real behavior beyond that: default page size of 50, cap of 200, and that total and next_offset signal whether more pages exist, plus the error behavior for bad sector/country values.

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?

Three dense sentences, front-loaded with what is returned, then filtering, then paging, then failure mode. No filler 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?

An output schema exists so return values need not be spelled out, and the description still covers scope, filtering, paging and error handling. Nothing needed to invoke it correctly 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?

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema lacks: the 50/200 paging behavior, the purpose of total and next_offset for continuing, and the fact that an invalid sector or country returns an error enumerating valid values. The query filter's cross-field matching is also restated usefully.

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

Purpose4/5

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

States a specific verb and resource ('Find covered companies and their tickers') plus the returned fields (latest quarter, next expected report date) and sort order. It is clearly a plural listing tool, which implicitly separates it from single-entity siblings like get_company, but no sibling is named explicitly.

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

Usage Guidelines3/5

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

It explains what each filter matches and that unknown sectors or countries error out with the valid list, which is useful context for calling it. It never states when to prefer this over search, list_recent or get_company, so the when-to-use decision is left to inference.

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