Clarifo

list_workspace_items

Read-onlyIdempotent

Find documents, notes, files and reports in the user's Clarifo workspaces. in_trash=true lists the trash instead (documents and notes moved there, newest first), for restore_from_trash.

Searches every workspace the user owns or has been shared, newest first, unless workspace_id narrows it. Returns metadata and a short preview; read an item with get_workspace_item. For "what have I written about X", pass company (the user's analyses linked to it, as on the company page's My Analysis tab); to ask how X has done since one of them, read it with view="since". When several items fit the user's words (same title in different workspaces), show them with workspace and date and let the user pick. origin says who produced an item when recorded (automate, clarifo_research, ai_client, chat); no origin means it was not recorded, not that the user wrote it.

Args: query: Words matched against titles and document text (all must match). workspace_id: Limit to one workspace. types: e.g. ["text"] for editor documents. Valid: text, source, analysis, search_result, chat_message, report, file, spreadsheet, visualization. Chat messages are left out unless listed here. only_unfinished: Only items still in progress (processing files, drafts). sort: updated_desc (default), created_desc, or position (needs workspace_id). limit: Items per page, 1-100 (default 20). cursor: next_cursor of the previous page. company: Company name or ticker (whole word: "Kone" is not Konecranes); items linked to that company, plus items whose title names it (company_match "linked" or "title"). published: true for the documents published on clarifo.com and still up ("my published articles"), false for the rest. An item's publication says its state and public url; the page shows what was published, and editing the document does not change it (publishing is done in Clarifo).

Returns: {"items": [{"item_id", "workspace_id", "workspace_name", "folder", "type", "title", "origin", "content_version", "updated_at", "preview", "editor_url", "match", "publication"}], "total": 334, "has_more": true, "next_cursor": "..."}

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_workspace_items"
  }
}

Input Schema

Name	Required	Default
`sort`	No	updated_desc
`limit`	No
`query`	No
`types`	No
`cursor`	No
`company`	No
`in_trash`	No
`published`	No
`workspace_id`	No
`only_unfinished`	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?

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the description adds non-redundant behavior: search scope covers every workspace owned or shared, default ordering is newest-first, chat messages are silently excluded unless types lists them, and trash listings are newest-first. It also explains the semantics of origin and publication so the agent does not misread absent 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?

Purpose and the trash/read alternatives are front-loaded, and the Args block is dense and skimmable. A few sentences run long (the published-state explanation about editing not changing publication) and could be tightened, but nothing is filler.

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 10-parameter search tool this covers everything an agent needs: what is searched, what is excluded, ordering, pagination, the mutating paths it enables (restore_from_trash), and disambiguation policy. A return shape is also spelled out even though an output schema exists.

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 carries the full burden and does: query is AND-matched against titles and text, types enumerates the valid values including the chat_message default-exclusion, sort lists all three modes and notes position requires workspace_id, cursor is the next_cursor from the previous page, company is whole-word matched and returns linked-plus-title matches, and published distinguishes live clarifo.com publications from the rest.

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?

Opens with a specific verb and resource set ("Find documents, notes, files and reports") scoped to "the user's Clarifo workspaces," and immediately distinguishes itself from get_workspace_item ("read an item with") and restore_from_trash (trash mode). An agent can pick this tool without opening any 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?

Explicit routing is provided for multiple cases: use get_workspace_item to read a hit, use in_trash=true when the user wants to restore, pass company for "what have I written about X", use view="since" to ask how a company has done since an analysis, and disambiguate by showing workspace and date when several items match. This is well beyond minimum viable guidance.

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.