The Contextium MCP Server is a knowledge management and team collaboration platform that connects your team's documentation, AI agents, skills, and workflows into MCP-compatible AI assistants (Claude Desktop, Claude Code, Cursor).
Core Resource Management
CRUD operations on files, libraries, agents, skills, workflows, tags, and members
Search — full-text, tag-based, and filename; plus link suggestions and file linking with bidirectional //fileId tokens
Version history for files; library trash with 30-day recovery
Workflows & Project Planning
load_workflow — bundle agents, skills, and libraries into a full session context
new_project / resume_project — guided or autonomous project setup without losing context
Phase management — add, reorder, update status, summarize, and delete project phases
manual_research_setup / auto_research_setup — research workspace creation
Task Management
add_task with auto-routing to the best-fit workflow and auto-assignment to the right member
update_task, list_tasks, break_down_task (AI-generated subtasks)
AI Agents & Skills
Create, update, delete agents with system prompts, personas, and roles
dispatch_agent_job / get_agent_job — autonomous AI execution with natural-language intent
list_skills, get_skill, update_skill from the workspace Skills Library
Identities
Create and manage AI identities (voice, tone, role, audience) for person, company, or hybrid contexts
Team Collaboration
notify_team_members about files, workflows, agents, or libraries
Access requests — request, approve, or deny access to private libraries/workflows
Workflow membership — share private workflows with viewer/editor roles
Activity logs — workspace, entity, and workflow activity digests
Notifications
Notification inbox (activity + broadcasts), unread filtering, mark-as-read, and preference management (per-type toggles, email frequency, Do Not Disturb)
File Sharing & Comments
share_create / list / revoke — public share links with permissions, expiry, and domain restrictions
add_comment, list_comments, resolve_comment — threaded comments with line-number anchoring
Integrations & Utilities
Figma sync — connect and sync Figma designs into libraries
Marketplace — browse, search, and install skills/agents/MCP servers
Third-party connectors (GitHub, Grafana, etc.) — brokered HTTP requests without exposing access tokens
contextium_status — workspace health dashboard; contextium_help — tool usage guide
Specialized Workflows
idea_kickoff — autonomous business analysis (SWOT, market sizing, competitor analysis, financials, go/no-go)
capture_idea — lightweight note saving into project seeds or Quick Notes
Enables syncing Figma designs into a Contextium library, bridging design files with team documentation.
Give Claude your team's brain. Pipe SOPs, coding standards, agents, and workflows directly into Claude Desktop, Claude Code, Cursor, and any MCP-compatible assistant.
Stop copy-pasting context into every chat. Contextium is a shared knowledge platform that connects your team's documentation, AI agents, skills, and workflows to Claude via MCP — so the right context is always there, automatically.
Ask Claude to create a Contextium project — it architects the full structure and populates it with content via MCP:
The result appears instantly in the Contextium Desktop app, ready for your whole team:
Related MCP server: repo-memory-mcp
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"contextium": {
"command": "npx",
"args": ["@contextium/mcp-server"]
}
}
}npx @contextium/mcp-server setupA browser window opens. Log in, select your workspace, and authorise. Done.
Contextium appears as running in Claude Desktop's Developer settings:
Say to Claude | What happens |
"Create a new Contextium project for our API docs" | Claude architects and populates a full library |
"Load my onboarding workflow" | Full team context loads into the session |
"Find anything about our authentication approach" | Searches across all your Contextium libraries |
"What agents do we have set up?" | Lists your team's AI agents with descriptions |
"Add this decision to our architecture library" | Creates a versioned file in Contextium |
"Browse the marketplace for a skill" | Searches and installs from the Contextium Marketplace |
Every tool ships with structured descriptions so Claude Desktop and other platforms understand exactly how and when to use each tool — no prompt engineering required on your end.
Tool | What it does |
| List any resource — workspaces, libraries, files, agents, skills, workflows, tags, members |
| Retrieve full details of any resource by ID — including member profiles |
| Create any resource — files, libraries, agents, skills, workflows, tags |
| Update any existing resource — files, agents, workflows, skills, tags |
| Delete files and resources (moves to trash, restorable) |
| Semantic search across all documentation |
| Filter resources by tag |
| Link agents to skills, apply tags, manage associations |
Tool | What it does |
| Load a full workflow — bundles agents, skills, and libraries into context |
| Guided flow to create a new Contextium project |
| Resume work from a previous session handoff |
| Structured feature development — get next phase, mark complete, close session |
Tool | What it does |
| List all skills in the workspace Skills Library |
| Retrieve a skill's full markdown content by ID or name |
| Update a skill's title or content |
Tool | What it does |
| Add a task to a workflow (accepts workflow name or ID) |
| Update a task's status — not_started, in_progress, done |
| List tasks for a workflow or across the workspace |
Tool | What it does |
| List all identities in the workspace |
| Retrieve full identity details |
| Create a new identity — voice, tone, role, and audience |
| Update an existing identity |
| Delete an identity |
Tool | What it does |
| Notify workspace members about a file, workflow, agent, or library |
Tool | What it does |
| Sync Figma designs into a Contextium library |
| Browse, search, and install from the Contextium Marketplace |
| Check auth status, current workspace, and available resources |
| Show available tools and usage guidance |
Claude Desktop
Claude Code
Cursor
Any MCP-compatible client
Requirements: Node.js ≥ 18
Request access to a private library or workflow you cannot see, or — as the resource owner — list, approve, or deny pending requests. Use action="request" when a loaded workflow reports a locked library (see its requestAccess affordance). This works from the terminal — the user does not need to open the web app.
| Name | Required | Description | Default |
|---|---|---|---|
| mine | No | For action=list: list your own requests instead of a resource's pending requests. | |
| action | Yes | request = ask for access; list = see requests (yours, or a resource's if you own it); approve/deny = resolve a request you own. | |
| reason | No | Optional note to the owner (action=request). | |
| requestId | No | The access-request ID. Required for action=approve/deny. | |
| resourceId | No | The library/workflow ID. Required for action=request. | |
| workspaceId | No | Workspace ID. Defaults to your default workspace. | |
| resourceType | No | Required for action=request (and action=list for a specific resource). | |
| rejectionReason | No | Optional reason shown to the requester (action=deny). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It mentions the tool works from the terminal but doesn't cover side effects, permissions, rate limits, or error handling. For a tool involving access control, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences front-loaded with the main purpose. Every sentence earns its place—no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 8 parameters and no output schema or annotations, the description provides a good overview of actions and usage. However, it could detail return values or error cases, though it remains fairly complete for a request tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The tool description adds context for the action enum and resource type but doesn't add meaning beyond what the schema provides. The schema's property descriptions are already clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: requesting access to private libraries/workflows and managing pending requests as owner. It specifies verbs (request, list, approve, deny) and the resource type, distinguishing it from any sibling tool that doesn't handle access requests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when to use action='request' ('when a loaded workflow reports a locked library') and notes it works from the terminal. It implies contexts for other actions but doesn't explicitly exclude alternatives or state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a comment to a file, or reply to an existing comment (pass parentCommentId). Authored as the connected user. Optionally anchor to a line with lineNumber. Replying to an external (guest) commenter also emails them.
| Name | Required | Description | Default |
|---|---|---|---|
| fileId | Yes | UUID of the file | |
| content | Yes | Comment text (plain text, max 10000 chars) | |
| lineNumber | No | Optional 1-based line to anchor the comment to | |
| parentCommentId | No | Optional comment id to reply to (from list_comments) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses authentication (authored as connected user), anchoring behavior (optional lineNumber), and email side effect for external replies. With no annotations, it covers key behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with primary action, every sentence adds value. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks return value details (e.g., comment ID or success indicator). No output schema, so description should fill that gap. Otherwise complete for a create tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters, but description adds context: content is plain text, parentCommentId sourced from list_comments, lineNumber is 1-based. Adds meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it adds a comment or replies, with specific verb and resource. It distinguishes from siblings like 'list_comments' (list) and 'resolve_comment' (resolve).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes when to use (add comment or reply) and a side effect (email to external commenters). Implicitly contrasts with siblings, but no explicit when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a phase (work item) to a workflow's project plan. Phases are appended at the end of the existing list. If the workflow has no project plan yet, one is created automatically.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Phase title — short, actionable description of the work. | |
| workflowId | Yes | Workflow ID | |
| description | No | Optional longer description or acceptance criteria. | |
| workspaceId | No | Workspace ID. Defaults to your configured workspace. | |
| assignedAgentId | No | Optional agent ID to assign this phase to. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that phases are appended and auto-creates a plan, but lacks details on side effects, permissions, error handling, return values, or what happens to optional parameters. Important behavioral traits for a mutation tool are omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both directly informative. The first sentence states the core purpose, the second adds key behavioral detail. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters (2 required), no output schema, and no annotations, the description provides adequate high-level behavior but lacks return value info, error handling, and specific parameter interactions. It is minimally complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter has a description. The tool description adds context about appending and auto-creation, but does not enhance parameter semantics beyond what the schema provides. Baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Add' and the resource 'phase (work item) to a workflow's project plan'. It distinguishes from sibling tools like delete_phase or update_phase_status by specifying the action and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions phases are appended at the end and that a project plan is auto-created if missing. However, it provides no explicit guidance on when to use this tool versus alternatives like add_task, nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a task — autonomous by default. Just pass a title and the server will (a) auto-ROUTE the task to the workflow it best fits (matched from the task text against workflow names/descriptions), falling back to the workspace's "General" workflow when no workflow clearly relates, and (b) auto-ASSIGN it to the right team member(s) by role/default. Every task belongs to a workflow — there is no workspace-level task. The caller does NOT need to choose a workflow or assignee. Provide an explicit workflowId/workflowName and/or assigneeIds ONLY to override that decision (the user has already decided) — explicit values are used verbatim and skip auto-routing/auto-assignment for whatever was specified. Set autoRoute:false to skip AI routing and place the task directly in the "General" workflow. Tasks are stored as DB tasks under the chosen workflow by default; only legacy workflows that still have a file-backed project library store the task as a phase file tagged "task".
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Task title — short, actionable description. | |
| dueDate | No | Optional due date — a calendar date "YYYY-MM-DD" or a full ISO 8601 datetime. Once set, the task surfaces in due-soon / overdue nudges. | |
| priority | No | Task priority — high, medium, or low. AI agents should set this based on urgency and importance. | |
| autoRoute | No | When true (the default) and no workflow is given, the task is auto-routed to the best-fit workflow, falling back to the workspace's "General" workflow if none relates. Set false to skip AI routing and place it directly in the "General" workflow. Ignored when an explicit workflowId/workflowName is provided. | |
| assignedTo | No | User ID to assign the task to. Overrides the workflow default assignee when provided. | |
| autoAssign | No | When true (the default) and no explicit assignee is given, the task is auto-assigned to the team member(s) whose job role best fits it. Set false to leave it unassigned. | |
| workflowId | No | Exact workflow ID. Use this when you already know the ID. | |
| assigneeIds | No | User IDs to assign this task to as a SHARED task that any one of them can complete (max 5). Only assign multiple people when the task genuinely needs more than one owner — do not blanket-assign. Prefer one assignee unless the task spans several roles. | |
| description | No | Optional longer description or context for the task. | |
| phaseFileId | No | Legacy: phase file ID to link this task to, for workflows still using a file-backed project library. New workflows use DB-backed phases (add_phase) and do not need this. | |
| workspaceId | No | Workspace ID. Defaults to your configured workspace. | |
| workflowName | No | Workflow name or partial name. Used to look up the workflow when you don't know the ID. If multiple workflows match, candidates are returned so the user can pick. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully discloses behavioral traits: auto-routing logic, fallback to General workflow, auto-assignment by role, override semantics, storage differences between legacy and new workflows. No contradictory annotations exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph that is information-rich without being overly verbose. Every sentence contributes value. However, it could be more scannable with bullet points or shorter sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 12 parameters, no output schema, and numerous siblings, the description covers the essential aspects: behavior, defaults, overrides, and storage nuances. It lacks mention of return value or error/validation behavior, but overall it's thorough for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant context beyond the schema descriptions, such as assigneeIds max 5 and the shared task concept, autoRule interaction with explicit workflowId, and legacy phaseFileId. The description enhances understanding meaningfully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Add a task — autonomous by default' and explains the core functionality of auto-routing and auto-assignment. It distinguishes this create operation from siblings like update_task and break_down_task by focusing on task creation with intelligent defaults.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when to use auto-features and when to override them with explicit workflowId/assigneeIds or autoRoute:false. It could be more explicit about when not to use this tool in favor of alternatives, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Autonomous one-shot project setup — creates a full Contextium workspace (library, agents, workflow, project-state.md) without asking any questions. Use when the user says "just set it up", "create a project for X", or is on mobile/voice.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Project name | |
| description | No | What the project is about — used to tailor agent system prompts | |
| workspaceId | No | Workspace ID (uses default if omitted) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It discloses autonomous behavior ('without asking any questions') and what is created, but lacks detail on side effects, prerequisites, failure modes, or idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no filler. Highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters and no output schema, the description outlines what the tool creates but omits return behavior, error handling, time expectations, or constraints like name uniqueness. Adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, meeting baseline at 3. The description adds value by explaining that 'description' tailors agent prompts and 'workspaceId' defaults if omitted, exceeding bare schema info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs autonomous one-shot project setup, specifying the exact resources created (library, agents, workflow, project-state.md). This distinguishes it from siblings like manual_project_setup and create_project.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists trigger phrases ('just set it up', 'create a project for X') and contexts (mobile/voice). Does not explicitly state when not to use or mention alternative tools, but provides solid guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Autonomous one-shot research workspace setup — creates a research library, agents, and workflow without asking any questions. Use when the user says "deep dive into X", "research X for me", or is on mobile/voice.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Research topic name | |
| depth | No | quick: one research agent + summary doc. deep: Research Lead + Fact Checker + structured brief. Defaults to quick. | |
| description | No | What to research — used to tailor agent system prompts and scope the brief | |
| workspaceId | No | Workspace ID (uses default if omitted) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description discloses autonomous behavior and lack of questions. However, it does not mention side effects like resource creation limits or permissions. Still, main behavioral traits are clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with clear usage examples. No unnecessary words. Front-loaded with purpose and usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters, no output schema, and no annotations, the description covers purpose and usage adequately. Lack of return value info is acceptable for a setup tool, but could be slightly more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds meaning by explaining depth options (quick vs deep) and how description parameter tailors agent prompts. Also notes workspaceId defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it is an autonomous one-shot research workspace setup that creates library, agents, and workflow without questions. It distinguishes from sibling manual_research_setup by specifying it requires no user interaction. Examples of when to use are given.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly specifies when to use: when user says 'deep dive into X', 'research X for me', or on mobile/voice. This helps differentiate from other research-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use AI to break a broad task into 3-6 concrete, actionable subtasks. Claude analyses the task title and workflow context, then creates the subtasks automatically. Use when a task is too broad to complete in one step.
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | Yes | ID of the parent task to break down. | |
| workflowId | Yes | Workflow ID that owns the task. | |
| workspaceId | No | Workspace ID. Defaults to your configured workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description says it 'creates subtasks automatically' but does not disclose if existing subtasks are replaced, idempotency, permissions, or side effects. Key behavioral details missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded, no fluff. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose and usage, but lacks description of return value/output (no output schema) and error conditions. Partial completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage 100% with descriptions for each parameter. Description does not add meaning beyond schema; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it breaks a broad task into 3-6 concrete subtasks, distinguishing it from sibling tools like add_task or update_task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear when-to-use guidance ('Use when a task is too broad to complete in one step') but lacks explicit when-not-to-use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture a quick note or seed to remember later — saves into an existing project's seeds or a general Quick Notes library. Use ONLY for lightweight "remember this" notes: when the user says "remember this", "note that", "jot this down", or "add this to [project]". Do NOT use this for a brand-new business, product, app, SaaS, or venture idea ("I have an idea for…", "I want to start a business that…", "I want to build…") — those are not quick notes; route them to idea_kickoff, which runs a full business analysis. When unsure between capturing and kicking off a venture idea, prefer idea_kickoff.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | The idea or note to capture | |
| projectName | No | Project to attach the idea to — inferred from existing projects if omitted | |
| workspaceId | No | Workspace ID (uses default if omitted) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses where the note is saved (existing project's seeds or Quick Notes library) but does not detail side effects, auth requirements, or potential destructive actions. Additional context would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded paragraph of about three sentences. It includes examples and exclusions without any fluff, making it efficient and focused.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple capture tool, the description covers purpose, usage guidelines, and parameter behavior. However, it lacks information about return values or confirmation of action, which is acceptable given no output schema, but could be slightly more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all three parameters. The description adds value by explaining that projectName is inferred if omitted (default behavior) and clarifies the role of workspaceId, going beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: capturing quick notes or seeds into projects or Quick Notes. It distinguishes from sibling tool idea_kickoff by specifying that this is for lightweight 'remember this' notes, not full venture ideas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use (lightweight 'remember this' notes with example phrases) and when not to use (new business ideas), and directs to idea_kickoff as alternative. It even advises to prefer idea_kickoff when unsure.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Make an HTTP request to a third-party platform that is allocated to a workflow, on the user's behalf. The request is brokered securely — you never see or handle any access token. Give the path RELATIVE to the connector base URL (e.g. "/repos/acme/api/issues"), not a full URL. Use list_workflow_connectors first to find a connector_id.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Optional JSON body for POST/PUT/PATCH. | |
| path | Yes | Path relative to the connector base URL, starting with "/". | |
| query | No | Optional query string incl. leading "?". | |
| method | Yes | HTTP method. | |
| workflowId | Yes | The loaded workflow that carries the connector. | |
| workspaceId | No | Workspace ID. Defaults to your default workspace. | |
| connector_id | Yes | connector_id from list_workflow_connectors. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the secure brokering of access tokens, which is a key behavioral trait. However, it does not mention error handling, rate limits, or other potential behaviors. Adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, each adding value: purpose + security, path format, prerequisite. No wasted words, information front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage, and parameters well, but lacks any mention of the response format or typical return values. Since no output schema exists, the description should have hinted at what the tool returns (e.g., raw HTTP response).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning beyond the schema by explaining the path format (relative to base URL), the security model, and the prerequisite to get connector_id. With 100% schema coverage, the baseline is 3; the extra context justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool makes an HTTP request to a third-party platform on behalf of the user, with a specific verb ('Make') and resource ('HTTP request'). It distinguishes from siblings by specifying the context (workflow connector) and referencing the prerequisite tool 'list_workflow_connectors'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool (after listing connectors) and how to format the path (relative, not full URL). It does not explicitly state when not to use it, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show all available Contextium capabilities and how to use them. Call this when the user asks: "what can Contextium do", "help with Contextium", "how do I use Contextium", "what Contextium tools are available", "show me what I can do with Contextium".
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden. It mentions showing capabilities and usage, which is transparent for a read-only help tool. No hidden behaviors need disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the first states purpose, the second lists trigger phrases. No wasted words, front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple help tool with no parameters and no output schema, the description is complete. It covers purpose and usage triggers adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the baseline is 4. The description does not need to add parameter information beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Show' and the resource 'all available Contextium capabilities and how to use them'. It distinguishes this help tool from the many specific action tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists trigger phrases like 'what can Contextium do', 'help with Contextium', etc., giving clear guidance on when to call this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show a Contextium workspace health dashboard — available workspaces, libraries, agents, skills, and workflows. Call this when the user asks: "check Contextium status", "what workspace am I in", "what resources do I have in Contextium", "show my Contextium setup", "what libraries do I have".
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceId | No | Workspace ID (uses default if omitted) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must carry the full burden. It implies a read-only operation by saying 'Show a health dashboard', but it doesn't disclose potential side effects, permission requirements, error behavior (e.g., invalid workspaceId), or return format. This is adequate but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence followed by relevant usage examples. It is front-loaded with the core purpose and avoids unnecessary words or repetition, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 optional parameter, no output schema), the description covers the main output categories (workspaces, libraries, agents, skills, workflows). However, it does not specify the response format or structure, which would be helpful for an agent to process results. Still, it is mostly complete for a dashboard tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a description for the only parameter ('Workspace ID (uses default if omitted)'). The tool description does not add any additional meaning or examples beyond what the schema provides, so it meets the baseline but doesn't enhance understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool shows a 'Contextium workspace health dashboard' and lists specific resources (workspaces, libraries, agents, skills, workflows). It provides concrete trigger phrases like 'check Contextium status' and 'what libraries do I have', making the purpose unambiguous and distinct from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to call the tool by listing user queries ('check Contextium status', 'what workspace am I in', etc.). This provides clear usage context and helps the agent select the right tool among many siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new resource in a workspace. Set type to what you're creating: "file" (needs libraryId + title + complete content), "library" (a context library — needs name), or "agent" / "skill" / "workflow" (need name; a workflow can bundle projectIds, agentIds, skillIds, and tagIds). Always provide full, real content for files — never empty or placeholder.
File linking: to link to another file in the SAME workspace, put // inline in the content — use the target file's UUID (from search/list/get results), not its title. The link renders as the target's title and is indexed automatically on save; the target gains a backlink with no extra step. Add a link only where the text genuinely references an existing file; never invent // for a file that does not exist (it becomes a dangling link). Use get({ type: "file_links", id }) to inspect a file's links and backlinks.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Name (type=library, agent, skill, workflow) | |
| path | No | File path (type=file) | |
| type | Yes | Resource type to create. (Tags are not created here — a tag exists by adding a #<value> token to a file's content; use manage_relationship type=tag to tag a file.) | |
| title | No | Title (type=file) | |
| tagIds | No | Workflow tag IDs (type=workflow) | |
| content | No | Full file content — must be complete (type=file) | |
| agentIds | No | Agent IDs (type=workflow) | |
| folderId | No | Folder ID (type=file) | |
| skillIds | No | Skill IDs (type=workflow) | |
| isPrivate | No | Workflow visibility (type=workflow). Defaults to true — visible only to you until shared. Set false to share with the whole team. | |
| libraryId | No | Library ID (type=file) | |
| projectIds | No | Workflow library IDs (type=workflow) | |
| description | No | Description (type=library, agent, skill, workflow) | |
| workspaceId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses key behaviors: mandatory full content for files, file linking syntax (//<fileId>), that tags are not created here, and default workspace visibility. However, it does not explain the return value or error conditions, which are important for a creation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively long due to detailed type-specific guidance and a separate paragraph on file linking. It is front-loaded with the main purpose, but the linking instructions add complexity. The length is justified by the tool's multi-type nature, but it could be more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 14 parameters, high schema coverage, and no output schema, the description provides a solid overview of creation behavior for each type. However, it omits expected return values (e.g., the created resource ID or object) and how it interacts with sibling tools, leaving some gaps for an agent using it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (93%), so the schema already documents most parameters. The description adds value for the 'type' parameter (clarifying how tags are created) and 'content' (requiring completeness and linking syntax). For other parameters like folderId, it adds nothing beyond the schema. Overall, moderate additional meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new resource in a workspace' and lists the supported types (file, library, agent, skill, workflow) with required fields for each. This provides a specific verb and resource scope. However, it does not explicitly differentiate from sibling tools like create_agent or create_project, which offer type-specific creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives detailed internal guidance on which parameters to use for each type, but it fails to mention when to use this generic create tool versus the type-specific sibling tools. There is no advice on alternatives or exclusions, leaving the agent without explicit decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new agent in the workspace.
WHAT IS AN AGENT: An agent is a specialised AI assistant with a defined role, persona, and behavioural instructions. Agents are where you put "You are a..." system prompts, persona definitions, tone of voice rules, and task-specific instructions. Agents can have skills attached to them to give them access to reference knowledge.
EXAMPLES of correct agent content:
"You are a senior customer support agent for Acme Corp. You handle billing and account queries..."
"You are a code reviewer specialising in Python. You check for security vulnerabilities..."
DO NOT use create_agent to store reference material, policies, or documentation — use create_skill for that.
IMPORTANT: You MUST always provide both a clear name AND a meaningful description — never leave description blank. The description should explain the agent's role, specialisation, and how it behaves.
WORKFLOW ATTACHMENT: Always provide workflowId when creating an agent for a specific project or feature — this ensures the agent is immediately attached to the right workflow and won't be orphaned.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | A clear, descriptive name for the agent (e.g., "Customer Support Agent", "Code Reviewer", "Marketing Copywriter") | |
| personaId | No | Optional persona ID to base this agent on a built-in persona. Use list_agents or get the persona list to find valid IDs. If provided, systemPrompt is derived from the persona. | |
| workflowId | No | Optional workflow ID to attach this agent to immediately after creation. Recommended — avoids orphaned agents. | |
| description | Yes | REQUIRED — A meaningful description of the agent's purpose, role, and behaviour. Explain what this agent specialises in, what tasks it handles, and how it should approach its work. Do NOT leave this blank. Example: "A customer support agent specialised in handling billing queries and account issues. Responds empathetically, escalates complex issues, and follows company refund policies." | |
| workspaceId | No | Workspace ID. If not provided, uses your default workspace. | |
| systemPrompt | No | The system prompt defining this agent's behaviour and instructions. Required for custom agents (when no personaId is given). Example: "You are a senior customer support agent. You handle billing queries empathetically and escalate complex issues." |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explains the behavior of creating an agent, what agents contain (system prompts, persona definitions), and the necessity of a meaningful description. It could mention side effects like cost or permissions, but overall provides good behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured into sections (WHAT IS AN AGENT, EXAMPLES, DO NOT, IMPORTANT, WORKFLOW ATTACHMENT) and is front-loaded with the main purpose. It is somewhat lengthy but each section earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple creation tool with no output schema, the description covers purpose, usage guidelines, parameter details, and workflow advice. It is complete enough for an AI agent to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 6 parameters with descriptions (100% coverage). The description adds value by explaining agent concepts and providing examples, but does not significantly enhance parameter meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'new agent in the workspace'. It explains what an agent is and distinguishes it from create_skill, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool (creating a custom AI assistant), when not to use (for reference material, use create_skill), and emphasizes required fields like name and description. It also advises attaching a workflow to avoid orphaned agents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a new identity in the workspace. Identities capture voice, tone, role, and audience context so AI produces work from the right perspective.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Identity name (required). | |
| type | No | Identity type. Defaults to person. | |
| scope | No | user: personal; workspace: shared. Defaults to user. | |
| neverDo | No | Things to never do. | |
| alwaysDo | No | Things to always do. | |
| audience | No | Intended audience. | |
| background | No | Background information. | |
| brandColors | No | Brand colours. | |
| roleContext | No | Role and context description. | |
| workspaceId | No | Workspace ID. If not provided, uses your default workspace. | |
| brandVisuals | No | Visual style description. | |
| writingSamples | No | Writing samples. | |
| recurringTopics | No | Recurring topics. | |
| linkedLibraryIds | No | Context library IDs to link. | |
| valuesPriorities | No | Values and priorities. | |
| voiceDescriptors | No | Voice and tone descriptors (e.g. "concise, direct, warm"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Only states basic action; no disclosure of permissions, reversibility, side effects, or rate limits. For a creation tool with 16 optional params, more behavioral context is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states action, second explains purpose. No redundancy or fluff. Front-loaded with core information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 16 optional parameters and no output schema, description is minimal. Lacks expected return value, error handling, prerequisites, or usage examples. Incomplete for a complex creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds general purpose but does not elaborate on any specific parameter beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Creates' and resource 'identity', and explains what identities capture (voice, tone, role, audience). Clearly distinguishes from siblings like update_identity and delete_identity by verb alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context on what identities are for but no explicit guidance on when to use this tool versus alternatives (e.g., update_identity). No exclusions or when-not-to use stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a phase plan for a workflow. A workflow can have at most one plan. Returns the new plan ID to use with add_phase. This is an alias of create_project.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Project plan name (defaults to the workflow name if omitted). | |
| spec | No | Optional full project spec stored on the plan record. | |
| workflowId | Yes | Workflow ID to attach the plan to. | |
| description | No | Optional short description of the project. | |
| workspaceId | No | Workspace ID. Defaults to your configured workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It mentions creating a plan and returning an ID, but omits details on permissions, side effects, or what happens to existing plans.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each purposeful: defines action, states constraint, gives return and alias. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description clarifies the tool's outcome and linkage to add_phase, but lacks explicit return structure details (e.g., response format) since there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining the return ID context for add_phase and the default for name, enhancing understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create a phase plan') and resource ('for a workflow'), and distinguishes itself from siblings by stating it is an alias of create_project and that the return is for add_phase.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a constraint ('A workflow can have at most one plan') which implies when not to use, but does not explicitly state when to use this tool versus alternatives like create_project.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a phase plan for a workflow (despite the name, this does NOT create a context library — it creates the project plan that holds phases). A workflow can have at most one plan. Returns the new plan ID to use with add_phase. Alias: create_plan.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Project plan name (defaults to the workflow name if omitted). | |
| spec | No | Optional full project spec stored on the plan record. | |
| workflowId | Yes | Workflow ID to attach the plan to. | |
| description | No | Optional short description of the project. | |
| workspaceId | No | Workspace ID. Defaults to your configured workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that a workflow can have at most one plan and that the tool returns a plan ID for use with add_phase. However, it does not discuss authentication, rate limits, or failure modes, which would be valuable for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the most critical information (what it does and what it does not do). Every sentence adds value, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description appropriately mentions the returned plan ID. It covers the key constraint (at most one plan) and provides an alias. For a creation tool with 5 parameters (one required), the description is reasonably complete, though it could mention error conditions or side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds context beyond the schema by explaining the return value (plan ID) and the relationship to add_phase, but it does not elaborate on each parameter further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool creates a phase plan for a workflow, clarifies it does NOT create a context library, and uses specific verbs and resources. It distinguishes from sibling tools like 'create_plan' (alias) and 'add_phase'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to create a phase plan) and mentions an alternative tool ('add_phase') to add phases to the plan. It also notes the alias 'create_plan'. However, it does not explicitly state when not to use or compare to other creation tools like 'create' or 'new_project'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Interactively create an agent, skill, or workflow in the current Contextium workspace. Call this when the user says things like: "create an agent", "make a new agent", "create a skill", "build a workflow", "I need a skill for X", "set up an agent that does X", "make an agent that can do X".
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Mentions 'interactively', suggesting user prompting, but does not disclose details like required inputs, side effects, or whether it modifies state. No annotations to supplement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences convey purpose and usage context efficiently. No unnecessary words, but structure is simple.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters or output schema, the description provides purpose and example intents but lacks details on return value and interactive behavior. Adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has zero parameters, so schema coverage is 100%. Baseline is 4, and the description adds no extra param info, which is acceptable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates an agent, skill, or workflow. It distinguishes from generic siblings like 'create' but not from specific ones like 'create_agent', which could cause confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides example user phrases, which imply usage, but lacks explicit guidance on when to use this tool over more specific siblings like 'create_agent' or 'create_skill'. No exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a resource (moves to trash, restorable). type: file | skill | workflow
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Resource ID | |
| type | Yes | Resource type: file | skill | workflow | |
| workspaceId | No | Workspace ID (required for workflow). If not provided, uses your default workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that deletion moves to trash and is restorable, which is a key behavioral trait beyond the basic destructive nature. Does not mention permissions or side effects, but the trash/restorable note adds value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with essential information and a list of types. No wasted words. Front-loaded with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with 3 parameters, no output schema, and no annotations, the description adequately covers the operation's effect (trash/restorable) and resource types. Could mention return status, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so description adds minimal new meaning beyond repeating the enum values for 'type'. Baseline 3 applies because schema already documents parameters. The description does not clarify format, constraints, or relationships.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'delete', the resource type with enumerations (file, skill, workflow), and distinguishes from sibling tools like delete_agent or delete_identity which are more specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for deleting resources of the listed types, but provides no explicit guidance on when to use this over more specific delete tools (e.g., delete_agent) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete an agent from the workspace. This cannot be undone. System agents (harness agents) cannot be deleted.
| Name | Required | Description | Default |
|---|---|---|---|
| agentId | Yes | ID of the agent to delete | |
| workspaceId | No | Workspace ID. If not provided, uses your default workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description bears the full burden of behavioral disclosure. It effectively communicates the destructive nature (permanent, cannot be undone) and a key constraint (system agents cannot be deleted). It could mention auth needs or confirmation steps but is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load essential information: purpose, permanence, and restriction. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with only two parameters and no output schema, the description covers all necessary context: destructive action, irreversibility, and a notable exception. It is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters well-described. The description does not add extra meaning beyond the schema (e.g., no explanation of agentId format or workspaceId resolution), so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as permanently deleting an agent, specifying the action ('delete'), the resource ('agent'), and adds critical context about permanence and system agent exclusion, distinguishing it from siblings like create_agent or list_agents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: it is for permanent deletion and cannot be undone, and explicitly states that system agents cannot be deleted. While it does not explicitly contrast with other deletion tools, the guidance is sufficient for most scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bulk delete all phases marked as done from a workflow's project plan. Use this to clean up completed work. Returns the number of phases deleted.
| Name | Required | Description | Default |
|---|---|---|---|
| workflowId | Yes | Workflow ID | |
| workspaceId | No | Workspace ID. Defaults to your configured workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool performs a bulk delete and returns the number deleted, but does not mention permissions, irreversibility, or side effects. For a destructive operation, more transparency is expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each adding value: function, use case, return value. No fluff, well-structured, and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a bulk delete tool with no output schema and no annotations, the description adequately states the action, condition, and return. Missing mention of potential cascading effects or undo options, but it is sufficient for a simple operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both workflowId and workspaceId are already described in the schema. The description adds no additional meaning beyond the schema, hence baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: bulk delete phases marked as done from a workflow's project plan. The verb "delete" and resource "phases marked as done" are specific, distinguishing it from sibling tools like "delete_phase" (likely single deletion) and "summarize_done_phases" (summary only).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says "Use this to clean up completed work," providing clear when-to-use guidance. It implies alternatives like "delete_phase" for individual deletion, but does not explicitly state when not to use or list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently deletes an identity by ID. Use dryRun=true first to preview which workflows will have their identity_id set to null.
| Name | Required | Description | Default |
|---|---|---|---|
| dryRun | No | If true, returns affected workflows without deleting. Default false. | |
| identityId | Yes | The ID of the identity to delete. | |
| workspaceId | No | Workspace ID. If not provided, uses your default workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explicitly states the deletion is permanent and recommends a dry run to preview impacts on workflows. This adds meaningful behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no fluff. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with 3 parameters and no output schema, the description adequately explains the operation and a best practice. It could mention permissions or irreversible nature more explicitly, but it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 does not add new meaning to parameters; it reiterates the dryRun purpose that is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it 'Permanently deletes an identity by ID.' This clearly specifies the verb and resource, distinguishing it from sibling tools like create_identity or update_identity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description suggests using dryRun=true first, which is a helpful guideline, but it does not explicitly mention when to use this tool over alternatives like the generic 'delete' tool or how it differs from other identity operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a context library (moves to trash, recoverable within 30 days). Requires owner or admin role.
| Name | Required | Description | Default |
|---|---|---|---|
| libraryId | Yes | The UUID of the library to delete | |
| workspaceId | No | Workspace ID (optional — uses default workspace if omitted) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that deletion moves to trash (recoverable within 30 days) and requires owner/admin. No annotations provided, so description carries full burden. Lacks side effects detail but sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, concise and front-loaded with the action and key constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple delete operation with 2 params and no output schema. Covers behavior, recovery, and role. Could mention irreversibility after 30 days but not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and description does not add meaningful details beyond schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it deletes a context library, distinguishes from restore_library and generic delete. Includes detail about trash and recovery.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Specifies when to use (delete library) and prerequisite role (owner/admin). Does not explicitly mention when not to use or alternatives, but role requirement is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a single phase from a project plan by its phase ID. Use this to remove a specific work item. To bulk-remove completed work, use delete_done_phases instead.
| Name | Required | Description | Default |
|---|---|---|---|
| phaseId | Yes | Phase ID (from list_phases or get_project) | |
| workspaceId | No | Workspace ID. Defaults to your configured workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states 'delete', which is inherently destructive, but lacks details on permanence, permissions, or cascading effects on associated tasks.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states the core action, second provides usage guidance and names the alternative. Every sentence is necessary and well-ordered.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with two documented parameters and no output schema, the description is sufficient. It covers what, how, and alternatives. Could mention if the operation is reversible or requires confirmation, but not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, already describing both parameters (phaseId and workspaceId). The description adds no extra meaning beyond 'by its phase ID', so it meets the baseline but doesn't add value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'delete', the resource 'single phase', and the method 'by its phase ID'. It differentiates from the sibling tool 'delete_done_phases' by noting it's for individual removal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (to remove a specific work item) and when not (use delete_done_phases for bulk removal). Provides a clear alternative sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dismiss a broadcast notification so it no longer appears in the inbox.
| Name | Required | Description | Default |
|---|---|---|---|
| broadcastId | Yes | ID of the broadcast to dismiss. | |
| workspaceId | No | Workspace ID. Defaults to configured workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must convey behavioral traits. It states the action and effect, but lacks detail on permanence, side effects, or permissions. For a simple dismissal, this is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no superfluous words, earning the highest score for conciseness and structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, no output schema, no annotations), the description is largely complete. It lacks mention of side effects or return behavior, but for a dismiss action with no output schema, this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with descriptions for both parameters. The description adds no extra meaning beyond what the schema already conveys, meriting the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('dismiss'), the resource ('broadcast notification'), and the outcome ('no longer appears in inbox'), effectively distinguishing it from related sibling tools like 'mark_notification_read'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool's purpose but provides no explicit guidance on when to use it versus alternatives (e.g., 'mark_notification_read'), nor does it specify prerequisites or non-use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dispatch an AI agent runner job with a natural-language intent. The runner autonomously selects the right agent, plans actions, and executes them. Returns a job ID you can poll with get_agent_job.
| Name | Required | Description | Default |
|---|---|---|---|
| intent | Yes | What you want the agent runner to do. Plain English — e.g. "Summarise the last 5 files in the Research library and write findings to a new file called Summary." | |
| workspaceId | No | Workspace ID. Defaults to your active workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden. It discloses autonomous selection, planning, execution, and async polling via job ID. Falls short of mentioning potential failure modes or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both essential. No filler, front-loaded with action verb 'Dispatch'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 simple parameters, no output schema, and no annotations, the description fully covers what the agent needs: purpose, input, return value, and next polling step.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds no additional meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool dispatches an AI agent runner job with a natural-language intent, and distinguishes it from sibling 'get_agent_job' by mentioning the returned job ID can be polled with that tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for high-level autonomous tasks, but does not explicitly state when not to use or list alternatives beyond 'get_agent_job'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage Figma connector integrations — list connected files or trigger a sync to pull design tokens, components, and page structure into your Contextium libraries.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | list: show all connected Figma files and their sync status; sync: trigger a full sync for a specific connection | |
| workspaceId | No | Workspace ID (uses default if omitted) | |
| integrationId | No | Integration ID of the Figma connection to sync (required for action=sync). Get this from action=list. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full transparency burden. It discloses that sync pulls specific data but omits behavioral traits such as whether listing is a read-only operation, if sync is destructive, authentication needs, or rate limits. Incomplete transparency for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the purpose ('Manage Figma connector integrations') and then details actions. Every word adds value with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's two actions, 3 parameters, and no output schema, the description covers the primary behaviors but does not hint at return values for sync, error conditions, or edge cases. It describes what list shows but not the format. Adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter described. The description adds value by explaining the action enum values ('list: show all connected Figma files and their sync status; sync: trigger a full sync...'), which goes beyond the schema descriptions. Minimal additional context for workspaceId and integrationId but overall helpful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool manages Figma connector integrations, listing connected files or triggering a sync to pull design tokens, components, and page structure. This specific verb+resource distinguishes it from sibling tools (no other Figma-specific tool).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (list or sync Figma connections) and is evident from the tool name and description. However, it does not explicitly state when to use vs. alternatives or provide exclusions. Clear but lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full details of a resource by ID. Use workspace_activity for recent activity logs. Use activity_archive to read a specific month's archived logs by YYYY-MM (e.g. 2025-02). Use list_activity_archives to see which months have archives. Use workflow_activity for the activity digest since a workflow's last session. Use entity_activity for recent activity on a specific file or entity.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Resource ID | |
| page | No | Page number for activity_archive (default 1, 100 rows per page) | |
| type | Yes | Resource type. file_links: the files a file links TO (forward) plus files that link to it (backward/backlinks) — id=fileId, optional direction. linked_mentions: backlinks with content excerpts (id=fileId). link_suggestions: find a file to link to by name (id=source fileId, query=search term). workspace_activity: recent workspace activity (use limit/userId/entityType/action to filter). activity_archive: archived month logs (id=YYYY-MM). list_activity_archives: see available archive months. entity_activity: recent activity for a specific entity (id=entityId, entityType required). workflow_activity: changes since last load (id=workflowId). member_profile: activity stats and recent actions for a member (id=userId). workflow_members: list who a private workflow has been explicitly shared with (id=workflowId). | |
| year | No | Filter to year e.g. 2026 (type=workspace_activity) | |
| limit | No | Max results. For workspace_activity: 1–200 (default 50). For file_versions and entity_activity: 1–20 (default 10). | |
| month | No | Filter to calendar month 1–12 (type=workspace_activity) | |
| query | No | Title or path to search for (type=file_by_path); search term (type=link_suggestions) | |
| scope | No | Search scope (type=link_suggestions, default workspace) | |
| action | No | Filter by action — created, updated, deleted, completed, etc. (type=workspace_activity) | |
| offset | No | Pagination offset (type=file_versions, workspace_activity) | |
| userId | No | Filter by user ID (type=workspace_activity) | |
| direction | No | Which links to return (type=file_links, default both) | |
| entityType | No | Filter by entity type — file, workflow, task, agent, member, etc. (type=workspace_activity, entity_activity) | |
| workspaceId | No | ||
| includeLinks | No | Also return the file's outgoing // links resolved to titles (type=file). Set true BY DEFAULT whenever a user asks to open/show/read a file: then add a one-line footer with how many files it links to, list them by title, and OFFER to open — do not auto-open. | |
| includeArchived | No | Include archived items (type=library_structure) | |
| includeMetadata | No | Include metadata (type=file) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full burden for behavioral disclosure. It states 'Get full details' implying a read operation, but does not mention any specific behaviors such as permissions required, rate limits, side effects, or the fact that the tool's behavior varies greatly by type parameter. The schema hints at different behaviors for different types, but the description does not elaborate. This is insufficient transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long. The first sentence states the core purpose concisely. The second sentence lists useful alternatives, which is valuable but slightly lengthens the description. Overall, it is efficient with minimal fluff, earning a 4.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 17 parameters and no output schema, the description is not fully complete. It does not explain what 'full details' includes, how pagination works, or what the return format is. The focus is on usage guidelines, which is good, but the description omits important behavioral context that would help the agent understand what to expect from the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (94%), so baseline is 3. The description does not add meaning beyond the schema; it only mentions 'by ID' which is already in the schema. The list of alternative tools in the description indirectly clarifies that the type parameter for activity types is not the primary use, but this is marginal. The description adds no new parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'resource by ID', and explicitly differentiates from sibling tools like workspace_activity, activity_archive, etc., by listing specific alternatives for activity-related tasks. This ensures the agent knows exactly what the tool does and how it contrasts with similar tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use alternative tools for activity logs (e.g., workspace_activity for recent logs, activity_archive for archived months). However, it does not cover when to use this tool over other non-activity tools like list or search, which are in the sibling list. The context is clear but lacks exclusions for other scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the status and result of a specific agent runner job. Poll this after dispatch_agent_job to check completion.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes | Job ID returned by dispatch_agent_job. | |
| workspaceId | No | Workspace ID. Defaults to your active workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. Discloses polling behavior but lacks details on rate limits, error handling, or safety of repeated calls. Minimal beyond what name implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with action and resource, zero waste. Efficiently conveys core information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple polling tool with 2 params and no output schema. Explains purpose and usage but omits return format or result structure. Could be improved with behavioral details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. Description adds value by linking jobId to dispatch_agent_job, providing cross-tool context. No further syntax details needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Get' with resource 'status and result of a specific agent runner job'. Distinguishes from sibling dispatch_agent_job and list_agent_jobs by specifying it returns status/result for a specific job.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states to poll after dispatch_agent_job to check completion, providing clear usage context. Does not discuss when not to use, but the polling pattern is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Gets the full profile of a single identity by ID, including voice descriptors, writing samples, and all contextual fields.
| Name | Required | Description | Default |
|---|---|---|---|
| identityId | Yes | The ID of the identity to retrieve. | |
| workspaceId | No | Workspace ID. If not provided, uses your default workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must convey behavior. It explicitly states the returned data includes profile, voice descriptors, writing samples, and contextual fields. This provides good insight into the tool's output, though it omits details about error handling or authorization.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded with the core action and specifics. No extraneous words; every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with two parameters, the description covers the purpose, resource, and output contents. However, the lack of an output schema means the description should also clarify possible error conditions or missing IDs, which it does not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters have clear descriptions. The tool description adds no further semantic value beyond what the schema already provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Gets' and resource 'full profile of a single identity by ID', and includes specifics like 'voice descriptors, writing samples, and all contextual fields'. It differentiates from sibling tools such as list_identities (list all), create/update/delete identity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a specific identity by ID, but does not explicitly state when to use this tool versus alternatives like list_identities or update_identity. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the notification inbox for the current user — both activity notifications and broadcasts.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max notifications to return (default 20). | |
| offset | No | Pagination offset (default 0). | |
| unreadOnly | No | Only return unread notifications. | |
| workspaceId | No | Workspace ID. Defaults to configured workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It implies a read operation but does not explicitly state that it is non-destructive, nor does it mention any limitations (e.g., it does not mark notifications as read). The description lacks behavioral details that would help avoid misunderstandings.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no unnecessary words, properly front-loaded with the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list retrieval with no output schema, the description is sufficient to understand what the tool does. However, it could be improved by briefly mentioning what the response contains (e.g., list of notification objects with fields). Given the context signals (4 params, no nested objects), the description is mostly complete but leaves the return format unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 adds no additional meaning beyond the schema-provided parameter descriptions. It does not explain parameter relationships or defaults beyond what is already stated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool retrieves the notification inbox for the current user, specifying it includes both activity notifications and broadcasts. This verb+resource combination is specific and distinguishes it from siblings like get_unread_count or mark_notification_read.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like get_unread_count, mark_notification_read, or dismiss_broadcast. The description states what it does but provides no context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the project plan attached to a workflow, including all its phases (open and completed). Returns phase titles, statuses, assigned agents, and sort order. Use this to understand what work is planned or in progress for a workflow.
| Name | Required | Description | Default |
|---|---|---|---|
| workflowId | Yes | Workflow ID | |
| workspaceId | No | Workspace ID. Defaults to your configured workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that both open and completed phases are returned, listing specific fields. However, it does not mention permissions, side effects, or pagination, leaving some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action ('Get the project plan attached to a workflow'), and every sentence adds value. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (get operation with two params), the description fully explains the return content (phases titles, statuses, agents, sort order) and purpose. No output schema is needed as the description covers it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described in the schema. The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'get' and the resource 'project plan attached to a workflow', including specific return fields (phase titles, statuses, agents, sort order). It distinguishes from siblings like 'project' by specifying attachment to a workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this to understand what work is planned or in progress for a workflow', providing clear when-to-use context. It does not mention exclusions or alternatives, but the use case is well defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the total number of unread notifications (activity + broadcasts) for the current user.
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceId | No | Workspace ID. Defaults to configured workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It states the tool returns a count for the current user, but does not disclose whether it is read-only, requires authentication, or how it handles missing workspaceId. However, the behavior is straightforward and the description is not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one optional parameter and no output schema, the description is largely complete. However, it could be slightly more complete by hinting at when to use it over siblings, but it adequately conveys the purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single optional parameter (workspaceId). The description adds no extra meaning beyond what the schema already provides ('Workspace ID. Defaults to configured workspace.'). Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get'), identifies the resource ('total number of unread notifications'), specifies the scope ('for the current user'), and clarifies that it includes both activity and broadcasts. This clearly distinguishes from sibling tools like 'get_notifications' which likely returns a list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives such as 'get_notifications', 'dismiss_broadcast', or 'mark_notification_read'. It does not mention use cases, prerequisites, or when a count is preferable to a list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Autonomous business-idea kickoff. Call this FIRST and IMMEDIATELY whenever a user voices a brand-new business, product, app, SaaS, startup, or venture idea — e.g. "I have an idea for…", "I have a business idea", "I want to start a business that…", "I want to build a product that…", "what if there was an app that…", "here's a business idea", "idea: …". Returns instructions to run a FULL business analysis autonomously — SWOT, market size (live TAM/SAM/SOM), competitor analysis with funding/revenue/valuation, build plan, RICE scorecard, timeline, roles, two-tier startup financials, and a synthesised go/no-go verdict — written as files into a dedicated project library. Do NOT present a "what do you want to do with this idea" menu and do NOT run the step-by-step new_project wizard: the idea IS the go-ahead, so just do the research. Use new_project instead for a feature inside an EXISTING product; use capture_idea only for a lightweight "remember this" note.
| Name | Required | Description | Default |
|---|---|---|---|
| idea | No | The business/product idea, in the user's own words — used to name the project and scope the analysis | |
| workspaceId | No | Workspace ID (uses default if omitted) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It details the autonomous analysis, writing files, and the list of components (SWOT, market size, etc.). Could mention potential side effects like overwriting files, but overall transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, detailed yet efficient. Includes examples and exclusions. Slightly long but each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description describes the return value (instructions for full analysis) and actions (writing files). Adequately covers inputs and outcomes for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions. The description adds value by explaining that 'idea' is used for naming and scoping, and 'workspaceId' defaults. Adds context beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: autonomous kickoff for new business ideas. It uses a specific verb and resource, and explicitly distinguishes from sibling tools like new_project and capture_idea.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit trigger phrases and instructs to call FIRST and IMMEDIATELY. Also tells what NOT to do (e.g., 'Do NOT present a menu') and specifies when to use alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all resources of a given type in a workspace — the fast way to see what already exists before you act. Returns lightweight summaries (IDs, names, key fields), not full content: use get for one resource's full detail, or search to find resources by text or tag. Set type to choose what to list — workspaces, libraries (context libraries), agents, skills, files (pass libraryId), workflows, tags, file_tags (pass fileId), workspace_status, or members (with roles + activity). Uses your active workspace when workspaceId is omitted.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Resource type to list. members: list all workspace members with their roles and activity status. | |
| fileId | No | File ID to list tags for (type=file_tags) | |
| status | No | Filter by status (type=files) | |
| folderId | No | Filter by folder (type=files) | |
| libraryId | No | Required when type=files | |
| workspaceId | No | Workspace ID (uses default if omitted) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It states it returns lightweight summaries (IDs, names, key fields) and uses active workspace by default. Could mention pagination or rate limits, but sufficiently transparent for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no fluff, front-loaded with purpose. Every sentence provides useful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explains return format (summaries). Covers all parameter contexts and common use cases. Complete for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage, baseline 3. Description adds value by explaining what each type returns (e.g., members with roles and activity) and specifying conditions (libraryId required for files).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all resources of a given type, using the verb 'list' and specifying the resource scope. It distinguishes from sibling tools 'get' (single resource detail) and 'search' (text/tag search).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'the fast way to see what already exists before you act' and provides when-not-to-use by referencing alternatives 'get' and 'search'. Also gives specific usage advice for each resource type.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recent agent runner jobs for the workspace — shows status (pending, running, done, failed), intent, and result summary.
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceId | No | Workspace ID. Defaults to your active workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions listing recent jobs with status, intent, result summary, but does not disclose ordering, pagination, limits, or authorization requirements. Adequate for a simple read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words. All key information is front-loaded: action, resource, and displayed fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter and no output schema, the description adequately covers what the tool does and what it returns. Lacks only minor details like default ordering or limit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single optional parameter 'workspaceId'. The description adds no additional meaning beyond the schema. Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list) and resource (recent agent runner jobs), and specifies what information is shown (status, intent, result summary). It is distinct from sibling tools like list_agents and get_agent_job.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like get_agent_job. The description implies it's for listing recent jobs but lacks when-not-to-use or alternative suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists all agents (AI assistant configurations) in a workspace. Agents define assistant roles and capabilities.
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceId | No | Workspace ID. If not provided, uses your default workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states the tool lists agents, failing to mention that it is a read-only, non-destructive operation, any required permissions, rate limits, or pagination behavior. The description lacks essential transparency for safe use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loading the core purpose. Every word is necessary; there is no redundancy. It efficiently communicates the tool's function and a brief definition of agents.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should explain return values or behavior. It does not mention what the output contains (e.g., list of agent objects with names and IDs), nor does it clarify the effect of the optional workspaceId parameter. The description is incomplete for a tool with minimal schema and no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (the workspaceId parameter has a description in the input schema). The tool description adds no additional parameter meaning beyond the schema. Baseline 3 is appropriate as the schema already documents the parameter adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all agents in a workspace and explains what agents are (AI assistant configurations). This distinguishes it from sibling tools like list_agent_jobs, which list jobs for an agent. The verb 'list' and resource 'agents' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as list_agent_jobs, list_comments, or list_tasks. It does not mention prerequisites, when to use the optional workspaceId, or any exclusions. The usage context is entirely implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the comments on a file — open (unresolved) threads by default. Comments are feedback to act on: each shows the author (members and external share-link guests), the anchored line number if any, and the comment id needed by resolve_comment / add_comment replies.
| Name | Required | Description | Default |
|---|---|---|---|
| fileId | Yes | UUID of the file | |
| includeResolved | No | Also include resolved threads (default false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It discloses the default filtering (unresolved only), fields shown (author, line number, comment id), and the purpose of the id. However, it omits operational details like auth requirements, rate limits, error handling, or pagination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. First sentence states purpose and default, second sentence elaborates on content and usefulness. Every sentence adds essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-param tool with no output schema, the description covers purpose, default, and content fields, but does not hint at the response structure (e.g., array of objects) or mention error scenarios, leaving minor gaps in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the default for includeResolved (false) and how the comment id links to other tools, providing context beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'List' and resource 'comments on a file', specifies default behavior (open threads), and distinguishes by mentioning the fields returned and linking to sibling tools resolve_comment/add_comment. The description leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage when needing to view file comments and obtain IDs for further actions, but does not explicitly state when to use this over other list tools (e.g., list_tasks) or when not to use it. No exclusions or alternative tool recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists identities visible to the current user in a workspace. Identities capture voice, tone, role, and audience context so AI produces work from the right perspective.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Filter by scope: "user" for personal identities only, "workspace" for shared identities only. Omit to return all visible identities. | |
| workspaceId | No | Workspace ID. If not provided, uses your default workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It mentions visibility and workspace context but omits behavioral details such as pagination, ordering, or whether the list returns all identities at once. Basic transparency is provided but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with two sentences that convey purpose and context without redundancy. It is front-loaded and efficient, though slightly more structure could improve scanability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with two optional parameters and no output schema, the description covers the core context (visibility, workspace, identity definition). It is mostly complete, though adding details about return structure would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters are well-described in the schema. The description adds context about identities but does not enhance parameter meaning beyond what the schema offers. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('lists identities'), the scope ('visible to the current user in a workspace'), and provides a helpful definition of identities. This distinguishes it from sibling tools like get_identity (single identity) or create_identity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (listing visible identities) but does not explicitly guide when to use this tool versus alternatives like get_identity or other list tools. No exclusion criteria or when-not-to-use advice is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all phases for a workflow's project plan, ordered by sort_order. Returns each phase with its ID, title, status (pending/in_progress/done/blocked), assigned agent name, and creation date. Use the phase IDs with update_phase_status to progress work.
| Name | Required | Description | Default |
|---|---|---|---|
| workflowId | Yes | Workflow ID | |
| workspaceId | No | Workspace ID. Defaults to your configured workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description covers ordering and return fields, but lacks explicit statements about side effects (read-only), pagination, or limits. Disclosure is adequate for a list operation but not fully comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three succinct sentences, front-loaded with the main action. No wasted words; each sentence adds value (action, returns, next step).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity, no output schema, and full parameter coverage, the description sufficiently explains what is returned and suggests a follow-up. Could mention if only active phases are shown, but not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds no extra parameter meaning beyond the schema. Baseline 3 is appropriate as it doesn't contradict or enhance significantly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists phases for a workflow's project plan, ordered by sort_order, and specifies returned fields. Distinguishes from sibling tools like add_phase, delete_phase, update_phase_status by focusing on listing and providing IDs for progression.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly guides to use phase IDs with update_phase_status, implying when to use this tool (before status updates). Does not provide when-not or comparisons to other list tools, but the hint is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tasks. Omit workflowId to list ALL tasks across every workflow in the workspace. Provide workflowId to list a single workflow's tasks instead; these are DB tasks by default, or phase files tagged "task" for legacy file-backed workflows. Returns status, creator, priority, and due dates. Use sparingly — load_workflow already includes active workflow tasks.
| Name | Required | Description | Default |
|---|---|---|---|
| mine | No | Cross-workflow listing only: return just tasks assigned to you plus unassigned ones. Ignored when workflowId is set. Default: false (all tasks across the workspace). | |
| status | No | Optional comma-separated status filter: not_started,in_progress,done,dismissed | |
| priority | No | Filter tasks by priority. Omit to return all priorities. | |
| workflowId | No | Workflow ID. Omit to list all tasks across every workflow in the workspace. | |
| workspaceId | No | Workspace ID. Defaults to your configured workspace. | |
| includeDismissed | No | Include dismissed tasks. Default: false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the tool's behavior: global vs. per-workflow listing, handling of legacy file-backed tasks, and that dismissed tasks are excluded by default. It implicitly indicates a read operation ('list'). However, it does not explicitly mention rate limits, pagination, or potential performance impact beyond 'use sparingly,' but for a list tool this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, front-loading the core function, then providing usage guidance, return information, and a caution. Every sentence adds value, and the structure is logical and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, no output schema, no annotations), the description covers key aspects: two usage modes, return fields, filtering options, and a performance warning. It does not mention pagination, error handling, or authentication, but these are less critical for a list tool. Overall, it's fairly complete for its purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions. The description adds significant meaning beyond the schema by explaining the behavioral implications of providing or omitting workflowId, and clarifying the default behavior for legacy tasks. This enriches the agent's understanding of parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'List tasks' and clearly distinguishes between two modes: listing all tasks across all workflows (omit workflowId) and listing tasks for a single workflow (provide workflowId). It also specifies what is returned (status, creator, priority, due dates), making the tool's purpose specific and distinguishable from siblings like add_task or load_workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to omit or provide workflowId, and advises 'Use sparingly — load_workflow already includes active workflow tasks,' providing clear context on when to use this tool versus an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all context libraries currently in the workspace trash (deleted within the last 30 days, not yet permanently removed).
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceId | No | Workspace ID (optional — uses default workspace if omitted) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool lists items in the trash that are within a 30-day window, but does not explicitly state that it is a read-only operation, nor does it mention authentication needs, rate limits, or other behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is well-structured and front-loaded with the key action and resource, containing no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains what the tool returns (list of context libraries in trash). It could mention pagination or sorting but is generally complete for a straightforward list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single optional parameter workspaceId. The description adds no additional meaning beyond what the schema already provides, meeting the baseline for this dimension.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'context libraries currently in the workspace trash', and adds specific scope: 'deleted within the last 30 days, not yet permanently removed'. This distinguishes it from sibling tools like restore_library or delete_library.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool (to view recently deleted libraries before permanent removal) but does not explicitly state when not to use it or mention alternative tools like restore_library for restoration or delete_library for permanent deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the third-party connectors allocated to a workflow (GitHub, Grafana, etc.). Use this to discover what connector_id values you can call with connector_request. You never see any access token — only connector ids and base URLs.
| Name | Required | Description | Default |
|---|---|---|---|
| workflowId | Yes | The workflow whose connectors to list. | |
| workspaceId | No | Workspace ID. Defaults to your default workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses a key behavioral trait: 'You never see any access token — only connector ids and base URLs.' This informs the agent that authentication credentials are not exposed, which is critical for understanding the tool's capabilities and limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences. The first sentence states the purpose, and the second provides the usage rationale. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, no output schema, and only two parameters, the description covers the essential aspects: what is listed (connectors), what is returned (ids and base URLs), and what is not (access tokens). It is complete enough for an agent to use without confusion.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 does not add significant meaning beyond the schema, except implicitly tying workflowId to the workflow context. The workspaceId is explained in the schema, and the description does not need to elaborate further. A higher score would require additional parameter-specific guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists third-party connectors for a workflow, with specific examples (GitHub, Grafana). It distinguishes from the sibling connector_request by noting that this tool is used to discover connector_id values. The verb 'list' is specific and the resource 'workflow connectors' is well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to use this tool to discover connector_id values for use with connector_request. While it does not list when not to use it, the context is clear given the sibling set. It provides a direct pointer to the next step, which is helpful for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Load complete workflow context — agents, skills, files, and libraries. Use this to initialise a full workflow session.
| Name | Required | Description | Default |
|---|---|---|---|
| workflowId | Yes | ||
| workspaceId | No | ||
| includeFileContent | No | Include full file content in response (default true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It only states the purpose without revealing side effects (e.g., whether it mutates state, requires authentication, or is safe to call multiple times). The term 'load' and 'initialise' suggest a setup operation, but behavioral details are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with two sentences: the first defines the action and resources, the second provides usage context. It is appropriately front-loaded and contains no unnecessary words, though it could benefit from slightly more detail without losing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three parameters, no output schema, and no annotations, the description is too brief. It does not clarify what 'complete workflow context' means in practical terms, the return format, or how the session initialization behaves. Key details about state changes and error conditions are absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool description does not explain any of the three parameters. Schema coverage is low (33%), with only includeFileContent having a description. The description mentions loading agents, skills, files, and libraries but does not map these to parameters, failing to add value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool loads complete workflow context including agents, skills, files, and libraries, and identifies its usage for initializing a full workflow session. While specific, it does not explicitly distinguish from sibling tools like get or get_project, but the bulk initialization intent is evident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises using this tool to initialize a full workflow session, providing a clear usage context. However, it lacks guidance on when not to use it or how it compares to alternatives (e.g., using get for individual components). No prerequisites or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage relationships: add/remove skills on agents, add/remove inline tags on files, and share/unshare a private workflow with an individual workspace member. For type=tag this EDITS THE FILE CONTENT — it writes (or deletes) a # token in the file body, which is the source of truth for a file's tags; the tag is auto-created if new. (Equivalent to updating the file content yourself.) For type=workflow_member, add is an upsert (re-adding an existing member updates their role).
| Name | Required | Description | Default |
|---|---|---|---|
| role | No | Access level for the shared member (type=workflow_member, action=add). Defaults to viewer. | |
| type | Yes | Relationship type. | |
| value | No | Tag value to add/remove (type=tag), e.g. "urgent". Lowercase letters, digits and hyphens; written into the file content as #<value>. | |
| action | Yes | Action. apply_bulk/remove_bulk: tag multiple files at once (type=tag, max 100). | |
| fileId | No | Single file ID (type=tag, action=add or remove) | |
| userId | No | Target workspace member's user ID to share the workflow with (type=workflow_member) | |
| agentId | No | Agent ID (type=agent_skill) | |
| fileIds | No | Multiple file IDs (type=tag, action=apply_bulk or remove_bulk, max 100) | |
| skillId | No | Skill ID (type=agent_skill) | |
| workflowId | No | Workflow ID (type=workflow_member) | |
| workspaceId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals important side effects for type=tag (edits file content, auto-creates tag) and workflow_member (upsert behavior), which goes beyond basic function. However, it lacks detail for agent_skill (no mention of side effects or permissions) and does not address reversibility or error cases for any type. With no annotations, the description carries the burden but is incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured into an overview sentence followed by detailed explanation per type. It is efficient with no wasted words, though it could be slightly shortened by consolidating repeated phrases.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of three relationship types and multiple actions, the description covers most behaviors for tag and workflow_member but leaves out details for agent_skill (e.g., what adding/removing entails). There is no output schema or error handling information, so an agent may lack full context to invoke the tool safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context beyond the schema: for 'value' it specifies the format and that it writes as #<value>; for 'role' it states the default; for 'fileIds' it mentions a max of 100. Schema coverage is 91%, so the description enriches already well-documented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly lists the three relationship types (tag, agent_skill, workflow_member) and their actions (add/remove/share), making the tool's purpose explicit and specific for each case. It distinguishes itself from other tools by covering multiple relationship management scenarios in one tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use each type (e.g., for tags it modifies file content, for workflow_member it shares with an individual), but does not mention alternatives from sibling tools like share_create or share_revoke, nor does it provide explicit guidance on when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Guided, interactive project setup — walks the user through creating a Contextium workspace step by step, asking for confirmation at each stage. Use when the user is present and wants to work through the setup together.
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceId | No | Workspace ID (uses default if omitted) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses interactive behavior and confirmation at each stage, but lacks details on side effects (e.g., workspace creation), required permissions, or output behavior. No annotations provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-loading purpose then usage, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adquately covers interactive nature and usage context for a simple tool, but doesn't mention expected output or post-setup state.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Parameter workspaceId is fully described in schema; description adds no additional meaning beyond that, so baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool's purpose: guided, interactive project setup for creating a Contextium workspace, distinguishing it from automated alternatives like auto_project_setup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use when the user is present and wants interactive setup, but doesn't state when not to use (e.g., for batch or non-interactive scenarios).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Guided, interactive research workspace setup — walks the user through creating a research workspace step by step. Use when the user is present and wants to steer the research direction.
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceId | No | Workspace ID (uses default if omitted) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions 'guided' and 'interactive' but does not disclose specific behaviors such as whether it creates resources, requires user inputs, or has side effects. The behavior is too vague for a tool that likely involves user interaction and potential changes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences. The first sentence states the core function, and the second provides usage guidance. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple schema (one optional param, no output schema) and interactive nature, the description provides basic context. However, it does not explain the outcome or what happens after the walkthrough, leaving the agent uncertain about the tool's effect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with clear descriptions. The tool description adds no additional meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a guided, interactive setup for a research workspace, distinguishing it from automated siblings. However, it does not explicitly differentiate from the similar sibling 'manual_project_setup'. The verb 'walks through' and resource 'research workspace' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises to use when the user is present and wants to steer the research direction, providing clear context. It implies not to use when user is absent or prefers automation, but does not explicitly state when not to use or list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Browse, inspect, and install shared skills, agents, and MCP servers from the Contextium Marketplace. Set action: "search" to browse listings (optionally filter by itemType skill/agent/mcp_server, category, or query); "get" for a listing's full details by slug; "install" to add a listing to a workspace by slug. Typically search first to find a slug, then get or install with it.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | Listing slug (action=get or install) | |
| query | No | Search query (action=search) | |
| action | Yes | search: browse listings; get: full details by slug; install: add to workspace | |
| category | No | Category filter (action=search) | |
| itemType | No | Filter by type (action=search) | |
| workspaceId | No | Target workspace (action=install) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that 'install' adds a listing to a workspace (mutative). However, it does not mention authorization requirements, reversibility, or any side effects. For a tool with both read and write actions, more transparency is expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loading the core purpose and then detailing actions with clear syntax. Every sentence is informative, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters, full schema coverage, and no output schema, the description provides a solid overview of how to use the tool. It explains the action sequence but does not hint at the return format of search or get results, which would enhance completeness slightly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, but the description adds value by grouping parameters by action (e.g., 'slug (action=get or install)' and 'query (action=search)') and explaining the workflow. This clarifies parameter usage beyond the schema's individual descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb-resource: 'Browse, inspect, and install shared skills, agents, and MCP servers from the Contextium Marketplace.' It distinguishes from siblings by focusing on marketplace-specific actions (search, get, install) that no other sibling tool covers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit instructions: 'Typically search first to find a slug, then get or install with it.' It also maps each action to its use case (search to browse, get for details, install to add). This gives clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark one notification as read, or mark all notifications as read when no ID is provided.
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceId | No | Workspace ID. Defaults to configured workspace. | |
| notificationId | No | Notification ID to mark read. Omit to mark all as read. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the burden of disclosing behavioral traits. It effectively communicates the two modes of operation (single vs. all) and implies a mutation (mark as read). However, it lacks details about side effects, reversion, or return values, which would enhance transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that conveys all necessary information without extraneous words. It front-loads the core action and efficiently covers both usage scenarios.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, two-parameter tool with no output schema, the description is sufficiently complete. It explains the tool's purpose and the conditional behavior based on the optional parameter. However, adding a brief note about typical use cases or expected behavior (e.g., 'This is a write operation') would make it slightly more robust.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers 100% of parameters with descriptions. The description confirms the behavior tied to the 'notificationId' parameter (omit to mark all) but does not add new semantic value beyond what the schema provides. It explains the default for 'workspaceId' subtly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action ('mark as read') and the resource ('notification'), and also distinguishes between marking one notification (with ID) and all notifications (without ID). This clearly differentiates it from sibling tools like 'get_notifications' or 'dismiss_broadcast'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use the tool (to mark notifications read) and explains the dual behavior based on whether an ID is provided. However, it does not explicitly state when not to use it or compare to sibling tools like 'dismiss_broadcast', which slightly reduces clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a guided new Contextium project setup. Call this tool FIRST whenever a user wants to set up a new project in Contextium, create libraries/agents/skills for a project, get started with Contextium, or organise their AI context. Returns complete step-by-step setup instructions that you must follow exactly.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It states the tool returns 'complete step-by-step setup instructions that you must follow exactly,' but does not reveal whether the tool has side effects (e.g., creates anything) or requires permissions. The lifecycle from this tool to actual project creation is unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with front-loaded purpose and usage. While concise, the structure could be improved by separating usage scenarios from behavior, but overall it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains that the tool returns instructions, but does not detail what those instructions contain or how the agent should proceed. Given no output schema, the agent may lack context for subsequent steps. The tool's role as a wizard starter is clear, but completeness is moderate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds value by explaining the tool's purpose and output, which compensates for the lack of parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as the initial entry point for project setup ('start a guided new Contextium project setup'). It distinguishes from siblings like 'create_project' and 'auto_project_setup' by emphasizing 'FIRST' and listing specific scenarios (set up project, create libraries, etc.).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to call this tool ('whenever a user wants to set up a new project...'), but does not explicitly mention when not to use it or directly name alternatives. However, the sibling list provides context, making the guideline clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Notify all eligible workspace team members about a resource you just created or updated — file, workflow, agent, or library. Use this when the user says things like "notify the team of this new file", "let everyone know about this workflow", or "notify @sarah about this". Respects each member's notification preferences and Do Not Disturb settings. Returns how many members were notified.
| Name | Required | Description | Default |
|---|---|---|---|
| message | No | Optional additional context to include in the notification | |
| memberIds | No | Optional list of member UUIDs to notify. Use memberNames or memberEmails instead when possible. | |
| resourceId | Yes | The UUID of the resource | |
| memberNames | No | Optional list of member display names to notify (case-insensitive). Prefer this when the user says things like "notify Sarah" or "notify Tom and Alice". | |
| workspaceId | No | Workspace ID (uses default if omitted) | |
| memberEmails | No | Optional list of member email addresses to notify. | |
| resourceName | Yes | Human-readable name of the resource, used in the notification text | |
| resourceType | Yes | The type of resource being shared | |
| notificationType | No | Notification preference type. Defaults to "newFileCreated". Use "mention" when notifying a specific person. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description discloses key behaviors: respects notification preferences and Do Not Disturb, returns count of notified members. Could add more on constraints (e.g., resource must be recently created/updated) but sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise sentences with no redundancy; purpose and usage are front-loaded. Every sentence adds necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters and no output schema, the description covers purpose, usage, behavioral traits, and return. Lacks details on permissions/ownership prerequisites but otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions. Description adds value by advising preference for memberNames over memberIds for user queries, but does not significantly enrich meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool notifies team members about a resource, listing specific resource types (file, workflow, agent, library) and example user phrases, distinguishing it from sibling tools like share_create or add_comment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage triggers with example user queries, but lacks explicit when-not-to-use guidance or alternative tool comparisons. Still clear for agents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
DEPRECATED — phases are now DB-backed. Use list_phases (replaces get_next_phase), update_phase_status(phaseId, "done") (replaces mark_phase_complete), and load_workflow (replaces load_session/close_session).
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Legacy file-based harness. get_next_phase: oldest pending phase FILE; mark_phase_complete: re-tag the phase FILE status:pending → status:passing and archive it; close_session: tag session log as closed; load_session: full project state | |
| workflowId | Yes | Workflow ID | |
| phaseFileId | No | Phase file ID (action=mark_phase_complete) | |
| workspaceId | No | Workspace ID (uses default if omitted) | |
| sessionLogFileId | No | Session log file ID (action=close_session) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It briefly describes each action's file-based operations (e.g., 're-tag the phase FILE status:pending → status:passing') but lacks details on permissions, side effects, or error handling. Adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with clear, front-loaded deprecation notice and structured list of alternatives. No unnecessary words; every part serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given five parameters, no output schema, and no annotations, the description covers high-level purpose and action mapping but omits return format, error conditions, and prerequisite checks. Acceptable for a deprecated tool but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents parameters well. The description adds context by linking parameters to actions but does not significantly enhance understanding beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool is deprecated and lists specific replacement tools for each action (e.g., list_phases, update_phase_status, load_workflow), clearly distinguishing from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-not-to-use instructions by marking the tool as deprecated and naming alternatives for each legacy action, leaving no ambiguity about when to avoid it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reorder the phases in a workflow's project plan. Provide the full list of phase IDs in the desired order; the plan's sort order is updated to match.
| Name | Required | Description | Default |
|---|---|---|---|
| orderedIds | Yes | Phase IDs in the desired order (typically the full set of phases for the plan). | |
| workflowId | Yes | Workflow ID | |
| workspaceId | No | Workspace ID. Defaults to your configured workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It states the effect ('the plan's sort order is updated to match'), but does not disclose potential side effects (e.g., whether old order is overwritten, if partial lists are rejected) or permissions needed. Adequate but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, no unnecessary words. The first sentence explains what the tool does; the second provides usage instruction. Highly concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple reorder tool with 3 parameters, no output schema, and no nested objects, the description covers the main action and key constraint (full list). It could mention validation or error cases, but overall it is sufficiently complete for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaningful context: 'Provide the full list of phase IDs in the desired order' reinforces the schema's 'typically the full set' note and clarifies that a partial list may not be accepted. This adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Reorder the phases in a workflow's project plan') and specifies the resource ('phases in a workflow's project plan'). The name 'reorder_phases' is self-explanatory. It distinguishes from sibling tools like 'add_phase' and 'delete_phase' by focusing on ordering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (to change phase order) and instructs to provide the full list of phase IDs. However, it does not explicitly state when not to use this tool or compare it to alternatives (e.g., updating individual phase statuses). The guidance is clear but minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve (acknowledge) a comment thread once it has been addressed — it disappears from default views everywhere (web, desktop, public share page, list_comments). Pass the ROOT comment id; the whole thread resolves. Set resolved=false to reopen.
| Name | Required | Description | Default |
|---|---|---|---|
| resolved | No | true = resolve (default), false = reopen | |
| commentId | Yes | Root comment id (from list_comments) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description discloses that resolving removes from all default views, that passing root comment id resolves whole thread, and that it can be reopened. Lacks permission details but adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words, front-loaded with main action. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 2 params and no output schema, description covers purpose, effects, parameter usage, and reopening. Complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond schema: clarifies commentId must be root comment id, whole thread resolves, and resolved defaults to true. Schema coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb (resolve), resource (comment thread), and effect (disappears from default views). Distinguishes from siblings like add_comment and list_comments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (once thread addressed) and how to reopen (resolved=false). Does not explicitly mention when not to use or alternatives, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restore a context library from trash. Must be within the 30-day restore window.
| Name | Required | Description | Default |
|---|---|---|---|
| libraryId | Yes | The UUID of the library to restore | |
| workspaceId | No | Workspace ID (optional — uses default workspace if omitted) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the time constraint but does not mention side effects, required permissions, or behavior if the library is not in trash or the window has expired. The description adds value beyond the schema by stating the restore window.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences, front-loading the main action and including the critical constraint. Every word adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple operation with two parameters and no output schema, the description covers the basic purpose and constraint. However, it lacks details on failure scenarios (e.g., expired window, library not in trash) and does not mention the outcome or integration with sibling tools like list_trash.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes both parameters. The description adds a usage constraint but does not provide additional semantic meaning for the parameters themselves beyond what the schema offers. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Restore a context library from trash' with a specific verb and resource, and it distinguishes from siblings like delete_library and list_trash by specifying the operation and the constraint of the 30-day restore window.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context for when to use this tool (to restore from trash) and includes the prerequisite condition of the 30-day restore window. However, it does not explicitly exclude other scenarios or mention alternatives like using list_trash to verify the library's presence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resume a Contextium project from a session handoff — loads the project plan, finds the last handoff note, and briefs you so you can continue without losing context. Call this when the user says things like: "resume my project", "continue where I left off", "pick up from last session", "what was I working on", "I'm back let's continue", "carry on from yesterday", "what's next in my project".
| Name | Required | Description | Default |
|---|---|---|---|
| workflowId | No | Workflow ID to resume (optional — if omitted, auto-selects if only one workflow exists) | |
| workspaceId | No | Workspace ID (uses default if omitted) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description must disclose side effects. It lists actions (loads, finds, briefs) but does not state whether it modifies state (e.g., marks handoff as read) or if it is a read-only operation. Lacks explicit behavioral cues.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with a list of examples. No filler, front-loaded with key action. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose and triggers well, but lacks details on return value or post-call state. For a tool with simple parameters and no output schema, this is sufficient but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already explains parameter behavior (auto-select, default). The tool description does not add new semantic value beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Resume a Contextium project from a session handoff' with specific actions: loads plan, finds last handoff note, briefs user. This distinguishes it from siblings like 'load_workflow' which may not include handoff context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit example utterances for when to call ('resume my project', 'continue where I left off'), giving clear usage context. Does not mention when not to use or alternatives, so slightly below perfect.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find files in a workspace when you don't know their exact ID. Pick a mode: "text" runs a full-text search over file contents and titles; "tags" returns files carrying ALL of the given tagIds (AND logic); "files" matches by partial file name/title. Reach for search before get when you only know roughly what you want; use list with type=files instead when you just need everything in a library. Optionally narrow to one library with libraryId.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | text: full-text search; tags: find files matching ALL specified tags (AND logic); files: find files by partial name/title match | |
| limit | No | ||
| query | No | Search query (mode=text or mode=files) | |
| offset | No | ||
| tagIds | No | Tag IDs to match (mode=tags) | |
| libraryId | No | Limit search to a specific library | |
| workspaceId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses behaviors such as the logic for each mode (AND for tags) and optional narrowing by libraryId. However, it does not mention pagination (limit/offset) or error handling, which would be useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loads the purpose, explains modes clearly, and provides usage guidance—all in two efficient sentences with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, no output schema), the description covers the main intent, mode selection, library narrowing, and sibling differentiation. It does not describe the return format, but it's fairly complete for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 57%. The description adds meaning beyond schema by explaining when to use each mode and the AND logic for tags. For parameters like limit, offset, and workspaceId, no additional info is provided, but overall it adds value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Find files in a workspace when you don't know their exact ID.' It also explains three distinct search modes (text, tags, files), which distinguishes it from siblings like 'get' and 'list'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: 'Reach for search before `get` when you only know roughly what you want; use `list` with type=files instead when you just need everything in a library.' This clearly tells the agent when to use this tool and when to use alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Suggest existing context libraries that look relevant to a workflow you are about to create, ranked by keyword overlap between the workflow name/description and each library's name/description. Call this BEFORE create_workflow (or create type=workflow) so you can present the matches to the user and let them choose which to attach via projectIds. Nothing is auto-attached — these are suggestions only. Returns [] when no libraries score above zero.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the workflow being created. | |
| description | No | The workflow description, if any — improves match quality. | |
| workspaceId | No | Workspace ID. If not provided, uses your default workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes ranking method (keyword overlap), return behavior ([] when no matches), and that it's suggestions only. No annotations provided, so description fully covers behavioral aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise two-sentence description that front-loads purpose, includes usage guidance and return behavior without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description states return value ('[]' when none). Parameter count 3, all explained with usage context. Sibling tools are many but description provides clear usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (baseline 3). Description adds context: 'name' is workflow name, 'description' improves match quality, 'workspaceId' defaults if omitted. This adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool suggests relevant context libraries based on keyword overlap, and distinguishes it from siblings by specifying it's for use before creating a workflow and that nothing is auto-attached.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance to call before create_workflow, explains that results are suggestions for user selection, and states that nothing is auto-attached.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate an AI summary of all done phases in a workflow's project plan, save it as a context file in the specified library, then delete the source phases. Updates the plan's last_summarized_at timestamp.
| Name | Required | Description | Default |
|---|---|---|---|
| libraryId | Yes | Library ID to save the summary file into. | |
| workflowId | Yes | Workflow ID | |
| workspaceId | No | Workspace ID. Defaults to your configured workspace. | |
| summaryTitle | Yes | Title for the summary file, e.g. "Auth Rewrite — June 2026". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states the destructive action ('delete the source phases') and the creation of a context file. Given no annotations, this disclosure is critical for safe invocation, though it could mention permanence or recovery options.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff, directly stating the purpose, the sequence of actions, and the side effect. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main workflow: summarize, save, delete, update timestamp. For a multi-step destructive tool with no output schema, it is fairly complete, though it lacks mention of prerequisites or reversal steps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds a real-world example for summaryTitle but does not significantly enhance understanding beyond what the schema already provides for the other parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates an AI summary of done phases, saves it to a library, deletes the source phases, and updates a timestamp. This specific combination of actions differentiates it from sibling tools like delete_done_phases, which only deletes without summarizing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. It does not mention prerequisites, when not to use it, or compare with similar tools like delete_done_phases or add_phase.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing resource in place by ID — edit a file's title, path, content, or status, or rename/reconfigure an agent, skill, workflow, or project. Only the fields you pass are changed; for files, a new version is created automatically so history is preserved. Set type to the resource kind and id to its UUID (from list/search/get).
File linking (type=file): to link to another file in the SAME workspace, put // inline in the content — use the target's UUID (from search/list/get results), not its title. The link renders as the target's title and is re-indexed on save; backlinks are automatic. To add a backlink to file B, add // to this file's content. Remove a link by deleting its // token. Only link to files that exist. Use get({ type: "file_links", id }) to inspect links and backlinks.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Resource ID | |
| name | No | New name (type=agent, workflow, project) | |
| path | No | ||
| slug | No | Slug (type=project) | |
| type | Yes | Resource type to update | |
| title | No | ||
| status | No | ||
| tagIds | No | Tag IDs (type=workflow) | |
| content | No | ||
| agentIds | No | Agent IDs (type=workflow) | |
| folderId | No | ||
| skillIds | No | Skill IDs (type=workflow) | |
| isPrivate | No | Workflow visibility (type=workflow). true = only you, the workspace owner/admin, and explicitly-shared members can see it. false = visible to the whole team. | |
| projectId | No | Move file to different library (type=file) | |
| projectIds | No | Library IDs (type=workflow) | |
| description | No | New description (type=agent, workflow, project) | |
| workspaceId | No | ||
| systemPrompt | No | System prompt (type=agent) | |
| changeSummary | No | ||
| createVersion | No | Create version history entry (default true) | |
| customContext | No | Custom context (type=agent) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that file updates create a new version automatically and explains the file linking mechanism. It mentions that only passed fields are changed, implying partial updates. It does not cover permissions, rate limits, or async behavior, but the disclosed behaviors are sufficient for basic usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose and then delves into file-specific details. It is well-structured with a general paragraph and a dedicated subsection for file linking. While somewhat lengthy, every sentence adds value, and the separation of concerns is clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 21 parameters and no output schema, the description covers the core behaviors and key parameters. It addresses file linking comprehensively but does not explain return values or versioning for non-file resources. The complexity is high, and the description provides sufficient detail for most use cases, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context beyond the schema, such as explaining that `id` must be a UUID from list/search/get, clarifying `isPrivate` for workflows, and specifying file linking syntax. Schema coverage is 67%, and the description compensates for several undocumented parameters (e.g., path, title) implicitly. However, some parameters like `workspaceId` and `changeSummary` lack extra guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts by clearly stating 'Update an existing resource in place by ID' and lists specific resource types like 'file, agent, skill, workflow, or project'. This distinguishes it from siblings like 'create' (new resources) and 'delete' (remove). The verb 'update' is specific and the resource scope is well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on partial updates ('Only the fields you pass are changed') and version history for files. It also details file linking syntax and backlinks. However, it does not explicitly state when not to use this tool (e.g., for deletion vs update), leaving some assumption to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Updates an existing identity by ID. Only the fields you provide are changed.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Identity name. | |
| type | No | Identity type: person, company, or hybrid. | |
| scope | No | user: personal (only visible to you); workspace: shared with all members. | |
| neverDo | No | Things to never do. | |
| alwaysDo | No | Things to always do. | |
| audience | No | Intended audience. | |
| background | No | Background information. | |
| identityId | Yes | The ID of the identity to update. | |
| brandColors | No | Brand colours. | |
| roleContext | No | Role and context description. | |
| workspaceId | No | Workspace ID. If not provided, uses your default workspace. | |
| brandVisuals | No | Visual style description. | |
| writingSamples | No | Writing samples. | |
| recurringTopics | No | Recurring topics. | |
| linkedLibraryIds | No | Context library IDs to link. | |
| valuesPriorities | No | Values and priorities. | |
| voiceDescriptors | No | Voice and tone descriptors (e.g. "concise, direct, warm"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden. It only says 'updates' and 'Only the fields you provide are changed', which is minimal. It does not disclose permissions, return values, or potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose. No wasted words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite high complexity (17 params, no output schema), the description is minimal. It doesn't clarify return value, transactional behavior, or workspace default behavior beyond schema. Incomplete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already described. The description adds the partial-update constraint but no additional meaning per parameter. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Updates an existing identity by ID.' which specifies verb and resource. It is distinguished from siblings like 'create_identity' or 'delete_identity'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying existing identities and mentions partial update behavior, but does not explicitly state when to use this tool versus alternatives like create or delete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update notification preferences for the current user — per-type toggles, email frequency, or Do Not Disturb.
| Name | Required | Description | Default |
|---|---|---|---|
| preferences | No | Per-type notification toggles, e.g. { "fileEdit": false, "mention": true }. | |
| workspaceId | No | Workspace ID. Defaults to configured workspace. | |
| doNotDisturb | No | Enable Do Not Disturb mode. | |
| emailEnabled | No | Master toggle for all notification emails. | |
| inAppEnabled | No | Master toggle for all in-app notifications. | |
| emailFrequency | No | How often to receive email digests. | |
| doNotDisturbUntil | No | ISO datetime to end DND (optional). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden. It states the action and scope (current user) but omits details like whether fields are merged or replaced, persistence, or side effects. Some transparency but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and main parameters. It is efficient and avoids verbosity, though a slightly structured list could improve readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 7 parameters and no output schema, the description covers the main functionality. However, it lacks information on default behavior for omitted fields, merge vs replace semantics, and response format, reducing completeness for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description adds limited value. It groups parameters functionally (per-type toggles, email frequency, DND) but does not explain behavior beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update notification preferences for the current user' with specific resources (per-type toggles, email frequency, Do Not Disturb). It distinguishes well from siblings like get_notifications and mark_notification_read.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for updating preferences but does not explicitly state when to use vs alternatives. There is no mention of when not to use or prerequisites, though siblings provide contrast.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the status of a project phase. Valid statuses: pending, in_progress, done, blocked. Use this to progress phases as work is completed. Setting a phase to "done" automatically records the completion time.
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | New status for the phase. | |
| phaseId | Yes | Phase ID (from list_phases or get_project) | |
| workspaceId | No | Workspace ID. Defaults to your configured workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses that setting status to 'done' auto-records completion time, which is valuable. However, does not mention if the operation is reversible, requires specific permissions, or returns data. Adequate for a simple state update.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-loading the purpose and key behaviors. Every sentence adds value: first sentence defines the action and valid states, second gives usage context and a notable side effect.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description covers core purpose, valid statuses, side effect of 'done', and usage context. Lacks mention of error conditions, prerequisites (e.g., phase must exist), or return value. Still sufficient for a simple tool with few parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already describes all 3 parameters with 100% coverage. The description adds the auto-record behavior for 'done' status, but that is a behavioral trait rather than parameter-specific detail. Minimal added value over schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action ('Update the status of a project phase'), resource ('project phase'), and lists valid statuses. Distinguishes from siblings like 'update_task_status' by focusing on phases and mentioning the auto-record behavior for 'done'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use it to progress phases as work is completed. Lacks explicit when-not-to-use or alternative tool suggestions, but the context is clear for typical workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a task title, description, or status. Works for all task types (DB tasks, phase tasks, file-backed tasks). Omit workflowId to update a task by id regardless of its workflow (the server resolves it). Use this instead of update_task_status when you also need to set a title or description.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | New title for the task. | |
| status | No | New status for the task. | |
| taskId | Yes | Task ID to update. | |
| workflowId | No | Workflow ID that owns the task. Omit to resolve the task by id regardless of its workflow. | |
| description | No | New description for the task. Pass empty string to clear. | |
| workspaceId | No | Workspace ID. Defaults to configured workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool works for all task types and explains the workflowId resolution behavior. However, it does not mention authentication requirements, side effects, or error scenarios. Still, the provided details are sufficient for an agent to understand core behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, with no extraneous information. Key points (updateable fields, task types, workflowId behavior, comparison to sibling) are presented succinctly and in a logical order.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 6 parameters and no output schema, the description covers the essential aspects: when to use, what fields can be updated, and the special behavior of workflowId. It does not describe the return value, but given no output schema requirement, this is acceptable. One could argue for a 5, but minor gaps (e.g., confirmation of update) prevent a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the effect of omitting 'workflowId' and confirming that 'description' can be cleared with an empty string (though the schema already mentions this). This extra guidance justifies a score of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb 'Update' and the resources 'task title, description, or status' and notes it works for all task types. It distinguishes itself from the sibling tool 'update_task_status' by stating when to use this tool instead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to use this tool over 'update_task_status' when also setting a title or description. Also explains the behavior of omitting 'workflowId' to update by task ID regardless of workflow, providing clear context on when to omit it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the status of a task. Omit workflowId to update a task by id regardless of its workflow (the server resolves it). Updates the DB task record; for legacy file-backed workflows it instead swaps the status tag on the underlying phase file. Use in_progress when starting work, done when complete, dismissed when no longer relevant.
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | New status for the task. | |
| taskId | Yes | Task ID to update. | |
| priority | No | Update the task priority. Optional — only set when changing priority. | |
| workflowId | No | Workflow ID that owns the task. Omit to resolve the task by id regardless of its workflow. | |
| phaseFileId | No | Legacy file-backed workflows only: link or update the phase file ID for this task. Pass null to clear the link. | |
| workspaceId | No | Workspace ID. Defaults to your configured workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses two distinct backend behaviors: direct DB update for modern tasks vs. tag swapping on phase files for legacy workflows. No annotations exist, so the description carries the full burden, and it does so adequately, though it omits error conditions or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each with a clear purpose: statement of action, workflowId behavior, backend modes, usage hints. Concise without redundancy, though it could benefit from a slightly more structured format (e.g., bullet points for usage hints).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 6 parameters (2 required) and no output schema, the description covers all key aspects: core operation, parameter semantics, and behavioral nuances. Missing details like error handling or exact response format, but the tool's behavior is well-explained for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds valuable context: the role of workflowId (omit for cross-workflow resolution), the purpose of priority (only when changing), and the special behavior of phaseFileId for legacy workflows. This goes beyond the schema's basic descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with "Update the status of a task," which is a specific verb and resource. It differentiates from sibling tools like update_task (general update) and update_phase_status (different resource) by focusing solely on status changes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on when to use each status value (e.g., 'Use in_progress when starting work') and clarifies the optional workflowId usage. However, it does not explicitly compare to alternatives or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
access_requestadd_commentadd_phaseadd_taskauto_project_setupauto_research_setupbreak_down_taskcapture_ideaconnector_requestcontextium_helpcontextium_statuscreatecreate_agentcreate_identitycreate_plancreate_projectcreate_resourcedeletedelete_agentdelete_done_phasesdelete_identitydelete_librarydelete_phasedismiss_broadcastdispatch_agent_jobfigma_syncgetget_agent_jobget_identityget_notificationsget_projectget_unread_countidea_kickofflistlist_agent_jobslist_agentslist_commentslist_identitieslist_phaseslist_taskslist_trashlist_workflow_connectorsload_workflowmanage_relationshipmanual_project_setupmanual_research_setupmark_notification_readmarketplacenew_projectnotify_team_membersprojectreorder_phasesresolve_commentrestore_libraryresume_projectsearchshare_createshare_listshare_revokesuggest_librariessummarize_done_phasesupdateupdate_identityupdate_notification_preferencesupdate_phase_statusupdate_taskupdate_task_statusMany tools overlap in purpose, e.g., multiple create tools (create, create_agent, create_resource, new_project), multiple project setup tools, and generic tools like 'get' and 'list' that cover many resource types. Descriptions help but boundaries are unclear, leading to potential misselection.
Most tools use snake_case verb_noun pattern, but there are deviations: 'project', 'marketplace', 'search' are nouns/verbs without underscore. Also, the variety of create tools (create, create_agent, create_resource, new_project) breaks consistency. Overall, mixed but still somewhat readable.
With 67 tools, the server is extremely bloated. A well-scoped server typically has 3-15 tools; this many creates cognitive overload and suggests the server tries to do everything, making it hard to navigate.
The server covers a wide range of features (project, tasks, agents, identities, sharing, notifications, connectors, marketplace), but there are notable gaps like no explicit task deletion tool. Some areas feel redundant or incomplete.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
shared AI-context layer for teams — persistent memory your agents search and update over MCP
One shared context your team's AI tools read & write over MCP. No re-explaining. Free.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/contextium-io/contextium-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
