Compass OS: Career

link roles

link_roles

DestructiveIdempotent

Record how the user reached a role from the one right before it at the same company: kind promotion, role-change, or separate (two separate jobs). Name the newer role by its company and title as get_profile shows them. grouped (promotion or role change only, default true) puts both roles under one company heading on the resume; false keeps separate entries. Use it once the user answers a step that get_profile, get_career_timeline or get_rewind marks as only suggested; to change a role's title, dates or accomplishments use update_profile. Only what the user said. It asks the user first, and leaves roles, dates and accomplishments as they are. A role with no earlier role at that company comes back as a miss. Once it's saved, undo can put it back within 24 hours.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "company": "<company>",
      "title": "<title>",
      "kind": "<kind>"
    },
    "name": "link_roles"
  }
}

Input Schema

Name	Required	Description
`kind`	Yes	How the user reached it: promotion, role-change, or separate (two separate jobs)
`title`	Yes	The newer role's title, exactly as get_profile shows it
`company`	Yes	The role's company, exactly as get_profile shows it
`grouped`	No	Promotion or role-change only: true (the default) puts both roles under one company heading on the resume, false keeps separate entries

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.

Changed1 schema field changedNov 5, 2026

addedOutput schema / properties / undo

Added value: +{
+  "description": "On a saved write: its undo handle, for undo within 24 hours",
+  "type": "string"
+}

Changed5 schema fields changedNov 4, 2026

addedInput schema / properties / company / description

Added value: +"The role's company, exactly as get_profile shows it"

addedInput schema / properties / grouped / description

Added value: +"Promotion or role-change only: true (the default) puts both roles under one company heading on the resume, false keeps separate entries"

addedInput schema / properties / kind / description

Added value: +"How the user reached it: promotion, role-change, or separate (two separate jobs)"

addedInput schema / properties / title / description

Added value: +"The newer role's title, exactly as get_profile shows it"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "text": {
+      "description": "The answer, or what was done, in plain words for the user: the same text as content",
+      "type": "string"
+    },
+    "widget": {
+      "description": "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",
+      "type": "string"
+    }
+  },
+  "required": [
+    "text"
+  ],
+  "type": "object"
+}

First observedNov 4, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Beyond the annotations (destructiveHint=true, idempotentHint=true) the description discloses that it asks the user first, that it leaves roles, dates and accomplishments untouched, that a role with no earlier role returns as a miss, and that undo can revert within 24 hours. These are real behavioral traits an agent could not infer from the structured fields. It stops short of describing the return payload in any detail, but an output schema exists, so this is close to complete.

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?

Purpose and constraints are front-loaded and every clause carries information, but the middle section packs several distinct rules into one dense paragraph, making it read as a run-on. Slightly tighter grouping (trigger, behavior, alternatives, undo) would improve scanability without losing content.

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 write tool with annotations plus an output schema, the definition covers the confirmation step, the mutation boundary, the edge case (no earlier role = miss), the undo window, and the sibling to use for a different edit. Nothing an agent needs in order 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.

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, but the description adds meaning: it explains that grouped changes how both roles are presented on the resume (one company heading vs. separate entries) and reiterates that title and company must match get_profile exactly, which is an operational constraint rather than a restatement. Marginal value above the schema, hence 4 rather than 5.

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: record how the user reached a role from the one immediately preceding it at the same company, and enumerates the three kinds. This clearly distinguishes it from update_profile (title/dates/accomplishments) and from get_profile/get_career_timeline which only report roles.

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?

It gives an explicit trigger (once the user answers a step that get_profile, get_career_timeline or get_rewind marks as only suggested) and an explicit exclusion with the correct alternative (to change a role's title, dates or accomplishments use update_profile). The 'only what the user said' constraint further bounds when it is appropriate.

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?