Clarifo

save_note

DestructiveIdempotent

Keep a short note in the user's Clarifo notes when the user asks to write something down or remember it ("note that", "write this down for Kone"). Prefer it to save_to_workspace for anything short or personal; a document is for a finished analysis. The note is the user's own text (no figure check), tagged with its companies so it shows on the company's research timeline in Clarifo and in notes(company=...).

Without note_id: a new note. With note_id (from notes): mode="append" adds the text at the end (continue a note), mode="replace" rewrites it only when the user asks (the old text comes back as previous_text), mode="rename" changes the title; companies alone just tag the note. Never deletes or empties a note. Say in a sentence what was saved and the companies it is tagged with, then show it with open_in_clarifo(note_id=...) instead of pasting note_url; give the link only when asked.

Args: idempotency_key: Optional; leave it out. Clarifo recognises a repeated identical request by its content. Give one only to retry this same request. text: The note, in the user's words; plain text, short paragraphs. companies: Companies the note is about (names or tickers, up to 5); each is resolved strictly; companies_not_found lists any that did not match: ask for the ticker and call again with note_id and companies. note_id: An existing note to continue, rewrite, rename or tag. mode: append (default), replace or rename; only with note_id. title: Optional title; a new note is titled by its first line.

Returns: {"status": "note_saved" | "note_extended" | "note_rewritten" | "note_renamed" | "note_tagged", "note_id", "title", "companies", "companies_not_found", "note_url", "previous_text"} or {"error", "failure_kind"}.

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

Input Schema

Name	Required	Default
`mode`	No	append
`text`	No
`title`	No
`note_id`	No
`companies`	No
`idempotency_key`	No

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 9, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Goes well beyond the annotations: it states that the note is the user's own text with no figure check, how tagging drives the company timeline, that replace returns previous_text, that nothing is ever deleted or emptied, how companies are resolved strictly with companies_not_found, and that an idempotency key should normally be omitted. The additive detail about overwrite recovery is exactly the kind of behavior an agent needs for a destructiveHint=true tool.

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 trigger and the sibling comparison, then moves to mode mechanics. Dense but every section earns its place; a few clauses, such as the response-formatting instruction, could be tightened without losing 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?

Covers trigger, alternative, all six parameters, mode semantics, failure handling, and error shapes for a mutation tool with six optional parameters. An output schema exists, yet the description still tells the agent the right follow-up action (open_in_clarifo, link only if asked), so nothing material is missing.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must carry all six parameters, and it does: text (plain, short paragraphs, user's words), companies (names or tickers, max 5, strict resolution), note_id, mode (append default / replace / rename), title (defaults to first line), and idempotency_key (omit unless retrying). This adds real semantics the bare schema cannot convey.

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?

Names a specific verb and resource ("Keep a short note in the user's Clarifo notes") plus the triggering user phrasings, and explicitly contrasts itself with save_to_workspace and documents. An agent can separate save_note from its closest sibling 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 when-to-use triggers ("note that", "write this down"), when to prefer it over save_to_workspace, when to supply note_id, which mode applies to which user intent (append by default, replace only when asked, rename for titles), and when to return the link versus calling open_in_clarifo. Exclusions and alternatives are both explicit.

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

All Clarifo 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.