Compass OS: Career

list companies

list_companies

Read-onlyIdempotent

List the companies the user follows (the Companies page): for each, the roles open for their job titles and which are new since the week before, posted pay for those roles, how many people they know there (a count, never names), the week it was last checked, its latest headlines (title and publisher) and its Trustpilot score when Trustpilot lists it. Use it for questions about companies they follow or are watching. Read-only. Facts come from each company's own job board, or a job search service when it has none, a news search and Trustpilot; there are no reviews, article text or details about people.

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

Name	Required	Description	Default
No arguments

Output Schema

Name	Required	Description
`text`	Yes	The answer, or what was done, in plain words for the user: the same text as content
`undo`	No	On a saved write: its undo handle, for undo within 24 hours
`widget`	No	The card the host draws with it, e.g. "pipeline"; "confirm" means a write waits for the user's Yes and nothing is saved yet

Schema Changelog

Changes observed during successful MCP inspections.

AddedNov 9, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already declare readOnlyHint and idempotentHint, but the description goes well beyond them by disclosing data provenance (company job board, job search service fallback, news search, Trustpilot) and a privacy constraint (people known is a count, never names). It also signals freshness via 'the week it was last checked', which an agent cannot infer from structured fields.

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?

The purpose and scope are front-loaded in the first clause, and the follow-up sentences on usage, read-only status and provenance each carry information. The long enumeration of returned fields is somewhat redundant given an output schema exists, which keeps it from a 5.

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 zero-parameter, read-only list tool with an output schema and full annotation coverage, the description supplies everything an agent needs: what is listed, what each entry contains, where the facts come from, and what is deliberately excluded. No material gap remains.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-parameter tool applies. The description adds no misleading parameter-like claims.

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?

The description opens with a specific verb and resource, 'List the companies the user follows (the Companies page)', and then scopes exactly what is returned per company. That is far more than a restatement of the name and makes the tool distinguishable from siblings like list_brand_posts or list_cases.

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

Usage Guidelines4/5

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

It gives a clear when-to-use cue: 'Use it for questions about companies they follow or are watching.' It also implicitly bounds scope by noting what is absent (no reviews, article text or people details). It does not name an alternative tool or state an explicit exclusion case, so it stops short of a 5.

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

All Compass OS: Career 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?