roTEAMnet — Global Job Search & Employer Discovery

search_companies

Read-onlyIdempotent

Discover employers in the public market snapshot by case-insensitive literal name substring. Omit q to browse ranked by posting count, then name. Returns generated_at, total, page, pages and at most 25 companies with public IDs, names, posting counts, remote_postings, top_countries and website detail URLs. These are snapshot counts, not guaranteed live vacancies or worldwide work eligibility; top_countries lists at most six countries per company. Empty or missing snapshot returns total=0, companies=[], page=pages=1 and nullable generated_at. Use search_jobs with an employer name to find current postings, then get_job for full details. No profile/CV, AI, credits or changes. Required scope: jobs:read

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

Name	Required	Description	Default
`q`	No	Optional literal employer-name substring; case-insensitive. Omit or leave empty for all snapshot employers.
`page`	No	One-based page, default 1, 25 employers per page. Out-of-range values clamp to the final page. Stop when returned page equals pages.

Output Schema

Name	Required	Description
`page`	Yes
`pages`	Yes
`total`	Yes
`companies`	Yes
`generated_at`	Yes	UTC snapshot timestamp; null if unavailable.

Schema Changelog

Changes observed during successful MCP inspections.

AddedOct 29, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is free; the description adds genuine value beyond that with the snapshot-vs-live caveat, the 25-per-page cap, the six-country truncation of top_countries, and the empty-snapshot return shape (total=0, page=pages=1, nullable generated_at). It also states the required jobs:read scope. Its only real omission is explaining why ranking is by posting count rather than, say, alphabetically, but the behavior itself is disclosed.

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-loaded with purpose and scope, then return shape, then caveats and routing — a sensible information order with no filler sentences. It is dense and packed into one paragraph, but every clause carries operational information.

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 two-parameter, read-only, zero-required-argument search tool, the description covers invocation, ordering, pagination termination, return fields, degradation on empty data, and cross-tool next steps. Nothing an agent needs in order to call it correctly is missing, even though the output schema makes some of the return-field detail redundant.

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 the baseline is 3. The description still adds meaning beyond the schema: default result ordering when q is omitted (posting count, then name), and the 'stop when returned page equals pages' termination rule, which is not in the schema's page description.

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 — 'Discover employers in the public market snapshot' — plus the matching mechanism (case-insensitive literal name substring). It also distinguishes itself from search_jobs by assigning that sibling the 'current postings' job, so an agent can separate the two without opening a 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?

Explicitly covers the no-argument case ('Omit q to browse ranked by posting count, then name') and names the follow-up path: use search_jobs with an employer name, then get_job. That is real when-to-use/when-to-use-something-else routing rather than implied guidance.

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

All roTEAMnet — Global Job Search & Employer Discovery tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?