This MCP server lets an AI interact with Axomind resources via bot API, exposing 26 tools for mindmap management, messaging, activity planning, and local directory-to-mindmap injection.
Mindmap tools (10): list mindmaps, read full/summary, get node descriptions, sync (destructive replace), append nodes, replace all (validated), safe single-node update/delete, and bulk style updates.
Messenger tools (4): send (targeted or broadcast), read, update, and delete bot messages in conversations.
Planning tools (9): high-level create/modify/verify assignments and read planning slots; low-level list activities, get activity, add/update/delete raw assignment JSON.
Tree/directory tools (3): scan a local directory to return compact telemetry, generate simplified mindmap nodes, or one-shot inject directory contents (with markdown→Quill Delta) into a mindmap.
Enables sending, retrieving, updating, and deleting bot messages via the Messenger platform.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@axomind-mcp list my activities"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
The MCP lives on the consumer side, not on the Axomind server. It contains no business logic — it makes HTTP POST requests to bot_api.php and returns the JSON. All security (auth, rate limiting, IP bans, bots @> checks) stays on the PHP side.
AI (any MCP client — Hermes, Claude, Cursor, etc.)
→ MCP server Python (FastMCP)
→ HTTP POST → bot_api.php
→ PHP does the work (auth, DB, WS notify)
← JSON response
← MCP tool result → AIRelated MCP server: telegram-api-mcp
This server exposes 26 bot tools that let an AI interact with Axomind resources where a bot is assigned:
Mindmap (10 tools) — read, create, update, delete nodes; manage styles
Messenger (4 tools) — send, read, update, delete bot messages
Planning (9 tools) — list activities, manage assignments, read time slots
Tree (3 tools) — scan local directories and inject them as mindmap structures
uv pip install -e .Dependencies: mcp (official SDK), httpx (HTTP client).
Copy .env.example to .env and fill in your bot credentials:
cp .env.example .envVariable | Description |
| URL to |
| Bot ID (from Axomind UI → bot management) |
| Bot access key (generated when creating the bot in the UI) |
Variable | Default | Description |
|
| HTTP timeout in seconds |
| — | Explicit path to |
Open Axomind desktop app
Go to bot management
Create a new bot → you get a Bot ID and a Bot access key
Assign the bot to the resources you want it to access (mindmaps, activities, conversations)
Put the credentials in your .env file
The bot can only access resources where its ID is listed in the bots JSONB column — this is enforced server-side by Axomind.
Tool | Description | Destructive? |
| List mindmaps where the bot is assigned (metadata only) | No |
| Read a mindmap (metadata + all nodes). ⚠️ Response can exceed 2 MB for 60+ nodes with descriptions | No |
| Compact summary — node count, titles, structure, has_description. Context-safe, no descriptions or styles | No |
| Read a single node's description by order_index (capped at ~4 KB). Use after | No |
| Replace ALL nodes (full JSON, ~25 fields per node). ⚠️ DESTRUCTIVE — sends 1 node → deletes the other 98 | ⚠️ Yes |
| Append nodes to an existing mindmap (simplified format). Reads existing, appends, syncs | No |
| Replace all nodes (simplified format). Validates hierarchy before sending | ⚠️ Yes (validated) |
| Update a single node — all fields supported (title, descriptions, parent, style, positions, free_links). Reads full mindmap, patches one node, syncs back. The algorithm handles the JSON, not the AI | No (safe) |
| Delete a node + its subtree. Cleans free_links pointing to deleted nodes. Root node (parent=0) cannot be deleted. The algorithm handles the JSON, not the AI | No (safe) |
| Update style fields on multiple nodes (color, bold, size_box, etc.). Reads, patches, syncs back | No (safe) |
update_node and delete_node are the safe way to modify a mindmap. They read the full mindmap, apply targeted changes to specific nodes, and sync everything back. Other nodes (including their descriptions) are preserved untouched.
The AI never builds the full node JSON — it passes only the fields to modify, and the algorithm does the rest:
// update_node: rename node 33
{"title": "messenger.md test"}
// update_node: change description (markdown → Quill Delta conversion is automatic)
{"descriptions": "# Module Messenger\n\nThis module handles..."}
// update_node: re-parent with cycle detection
{"parent": 2}
// update_node: change style + propagate to children
{"color": "0xFFFF6F91", "bold": true, "is_write_children": true}
// delete_node: just the order_index, no JSON at all
// delete_node(id_mindmap=100, order_index=33)Validations enforced by the algorithm (not by the AI):
Self-reference: parent == order_index → rejected
Cycle detection: new_parent is a descendant of order_index → rejected
Parent must exist in the mindmap
Root node (parent=0) cannot be deleted
free_links cannot target self, all targets must exist
size_box must be 0–11
replace_mindmap / add_nodesThe AI provides a compact JSON — the MCP auto-expands ~25 default fields:
[
{"title": "Root", "parent": 0, "color": "0xFFF0BA6D", "size_box": 2, "bold": true},
{"title": "Category A", "parent": 1, "color": "0xFF7A8FF5", "size_box": 1, "line_style": 1},
{"title": "Item 1", "parent": 2},
{"title": "Item 2", "parent": 2, "color": "0xFFFF6F91", "free_links": [3]}
]Fields:
title (required) — node title
parent (required) — order_index of the parent node (0 = root, 1 = first node)
color (optional) — hex color (default: 0xFF7A8FF5)
pos_x, pos_y (optional) — canvas position (default: 0)
size_box (optional) — 0=normal, 1=category, 2=root (default: 0)
bold, italic, underline (optional) — text style
line_type (optional) — 0=curve, 1=rounded, 2=square
line_style (optional) — 0=solid, 1=dashed
stroke_width, dot_radius, radius, border_size, label_size (optional)
icon_id (optional) — icon ID
active_bg_colors (optional) — active background colors
descriptions (optional) — descriptive text (markdown → Quill Delta)
free_links (optional) — list of order_index for free links between nodes
spacing_h, spacing_v (optional) — spacing multipliers (0-10)
is_write_children (optional) — propagate style to children (one-shot)
UID and order_index are assigned automatically. add_nodes reads the existing mindmap and appends after existing nodes.
These tools scan the local filesystem to build mindmap structures from directory trees.
Tool | Description | HTTP? |
| Compact telemetry of a directory (title, type, size, hierarchy). Does NOT read file content. Use before injection to get a reference node count | No (local) |
| One-shot scan + read + inject — scans the directory, reads | Yes (sync_nodes) |
| Scan → JSON nodes (simplified format, no file content). Ready for | No (local) |
1. tree_scope(root_path, root_title) → reference count (1 root + N dirs + M files)
2. inject_directory_to_mindmap(root_path, root_title, id_mindmap) → scan + read + Quill Delta + sync
3. Compare the returned summary (total_nodes, descriptions_filled, errors) with tree_scope count
4. If they match and errors is empty → injection validated. DONE.Only .md, .markdown, .txt files are read and converted to Quill Delta
Files > 500 KB and non-text formats (.docx, .pdf, images) get nodes with empty descriptions
Hidden files and VCS directories (.git, node_modules, __pycache__) are skipped automatically
Never call get_mindmap to verify an injection — the summary + tree_scope count are sufficient
Tool | Description |
| Send a message (targeted or broadcast to all conversations) |
| Read bot messages in a conversation |
| Update a bot message |
| Delete a bot message |
All planning tools use the bot API (bot_api.php → api_activity route). The bot operates as the bot owner's user_id — the same authentication chain as add_assignment / update_assignment / delete_assignment.
Tool | Description |
| Create an assignment (single-day or recursive) with human-friendly params (dates, hours, weekday names). Builds the JSON internally |
| Modify an existing assignment group. Server marks tombstone, removes old slots, creates new ones |
| Read an activity and return a telemetry report (groups, slots, consistency checks) |
| Read all planning slots for a given year via the bot API. Returns actual time slot data (start/end times, day of year, user assignments) and group controls. Uses |
Tool | Description |
| List activities where the bot is assigned |
| Read a specific activity (full metadata) |
| Assign time slots (raw |
| Update an assignment group (raw JSON) |
| Delete an assignment group |
The MCP provides a 3-tier reading strategy to keep AI context small:
list_mindmaps() — metadata only (id, title, participants). No nodes.
get_mindmap_summary(id_mindmap) — compact summary: node count, titles, structure, has_description flag. No descriptions, no positions, no styles.
get_node_description(id_mindmap, order_index) — read a single node's description (capped at ~4 KB).
The AI should never call get_mindmap (full) unless it needs to inspect individual node fields before a modification. For understanding structure, use get_mindmap_summary. For reading content, use get_node_description on specific nodes.
To consume the Axomind Bot API from Hermes, add the MCP server to ~/.hermes/config.yaml:
mcp_servers:
axomind:
command: "python3"
args: ["-m", "axomind_mcp.serveur.server"]
env:
# Bot API — URL to bot_api.php on the Axomind server
AXOMIND_BASE_URL: "https://quantive-studio.fr/app/bot_api.php"
# Bot credentials (from Axomind UI → bot management)
AXOMIND_BOT_ID: "<your_bot_id>"
AXOMIND_BOT_KEY: "<your_key_access>"
# Python import path (required — workdir sets cwd but not the import path)
PYTHONPATH: "/path/to/axomind-mcp/src"
workdir: "/path/to/axomind-mcp"⚠️ All env values must be strings (YAML parses 72 as int → pydantic rejects it).
⚠️ PYTHONPATH is required — workdir sets the cwd but not the Python import path.
After editing the config, restart Hermes or run /reload-mcp — the 26 tools are discovered automatically with the mcp_axomind_ prefix (e.g. mcp_axomind_list_mindmaps, mcp_axomind_send_message, mcp_axomind_read_planning).
Use the same env vars and command. The MCP server uses standard stdio transport.
PYTHONPATH=src python -m pytest tests/ -v149 tests — mock httpx, no network calls to the Axomind server.
src/axomind_mcp/
├── __init__.py
├── _common.py — FastMCP instance, env config, _post() helper, node defaults
├── _planning.py — 9 tools planning/activity (bot API)
├── imports.py — Single import hub (registers all @mcp.tool() decorators)
├── messaging/ — Messaging tools
│ ├── __init__.py
│ └── _messenger.py — 4 tools messenger (bot API)
├── serveur/
│ ├── __init__.py
│ └── server.py — Entry point stdio, mcp.run()
├── mindmap/
│ ├── __init__.py
│ ├── _mindmap.py — 10 tools mindmap (bot API)
│ ├── node_operations.py — Shared algo: update/delete/patch nodes, cycle detection, style propagation
│ └── config_layout_mindmap.py — Node expansion, validation, auto-positioning
└── tools/
├── __init__.py
├── _file_reader.py — File reading by extension → Quill Delta
├── md_to_quill_delta.py — Markdown → Quill Delta converter
└── _tree.py — 3 tools tree (local + bot API)The MCP does not touch the database or contain any business logic
Credentials come from environment variables (never hardcoded)
The Axomind server cannot tell it's a MCP — it sees normal bot_api requests
Tree tools (local filesystem scan) only scan the local machine where the MCP runs
The .env file path is set via AXOMIND_ENV_FILE — not discoverable from the public repo
Proprietary — see LICENSE. Copyright © 2025 VEZZANI Sébastien. All rights reserved.
Assign time slots to an activity by creating a new recursive group.
A recursive group defines a date range and recurrence pattern. The planning list defines the time slots within each day of that range. Together they form a complete assignment that appears on the activity timeline.
Args: id_activity: Activity ID planning_list: JSON string — array of day slots. Each element: { "id": "0", # 0 for new slots "slot_year": 2026, # year of the slot "index_position_jour": 1, # day-of-year (1-365/366) "rel_id_user": 2, # user ID the slot belongs to "taches": [ # time slots within the day { "id": "0", "rel_id_planning_day": "0", # 0 for new "rel_id_activity": , "group_control_id": "0", # 0 for new (assigned server-side) "start_time": "08:00:00", # HH:mm:ss "end_time": "12:00:00", # HH:mm:ss "maj_datetime": "2026-06-23T10:00:00.000Z" # ISO 8601 UTC } ], "maj_datetime": "2026-06-23T10:00:00.000Z" } recursive_group: JSON string — the group definition: { "id": "0", # 0 for new group "id_activity": , "titre": "Weekly morning", # group title "notes": "", # optional notes "start_date": "2026-06-01T00:00:00.000Z", # ISO 8601 UTC "end_date": "2026-06-30T00:00:00.000Z", # ISO 8601 UTC "active_days": 127, # bitmask: bit 0=Mon, 1=Tue, ... 6=Sun "created_by": 2, # user ID of the creator "created_datetime": "2026-06-23T10:00:00.000Z", "maj_datetime": "2026-06-23T10:00:00.000Z" }
Returns: JSON string — server response with created slot IDs and group ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id_activity | Yes | ||
| planning_list | Yes | ||
| recursive_group | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 explains the function (creates a recursive group and planning list), the structure of inputs, and the return type (JSON string with IDs). However, it does not describe side effects (e.g., whether it invalidates caches, requires specific permissions, or has rate limits). The description is adequate but not comprehensive 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 longer than necessary, but it is well-structured with a clear purpose statement, labeled parameter details, and a return description. The front-loaded purpose sentence is effective. However, the inclusion of full example JSON structures, while valuable, adds verbosity. It could be slightly more concise without losing critical 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 the complexity of the tool (creating assignments with recurrence), the description is fully complete: it explains the concept of recursive groups and planning lists, details all input parameters with field-level documentation, and describes the return value. The absence of an output schema is mitigated by the description of the return as a JSON string with created IDs. No gaps remain.
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 only titles with no descriptions (0% schema description coverage). The tool description compensates fully by detailing the structure and required fields of 'planning_list' and 'recursive_group' with example JSON snippets and field-level explanations. For 'id_activity', it simply restates the schema, but overall the description adds essential meaning beyond what the schema offers.
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: 'Assign time slots to an activity by creating a new recursive group.' It uses specific verbs and resources, but it does not differentiate from the sibling tool 'create_assignment' or clarify the distinction between similar assignment-related tools. Hence, while purpose is clear, sibling differentiation is missing.
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 like 'create_assignment', 'modify_assignment', or 'update_assignment'. It implies usage for creating recurring assignments, but does not state prerequisites, context, or cases where another tool would be more appropriate. This leaves the agent uncertain about selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append nodes to an existing mindmap (simplified format).
Unlike sync_nodes which replaces everything, add_nodes reads the existing mindmap, appends the new nodes, and syncs the full set.
Simplified node format (JSON string): [ {"title": "Node 1", "parent": 0, "color": "0xFF7A8FF5"}, {"title": "Node 2", "parent": 1, "color": "0xFFFF6F91"}, {"title": "Node 3", "parent": 1} ]
Fields:
title (required): node title
parent (required): order_index of the parent node (0 = root)
color (optional): hex color (default: 0xFF7A8FF5)
pos_x, pos_y (optional): canvas position (default: 0)
size_box (optional): 0=normal, 1=category, 2=root
bold, italic, underline (optional): text style
line_type (optional): 0=curve, 1=rounded, 2=square
line_style (optional): 0=solid, 1=dashed
stroke_width, dot_radius, radius, border_size, label_size (optional)
icon_id (optional): icon ID
active_bg_colors (optional): active background colors
descriptions (optional): descriptive text
free_links (optional): list of order_index for free links. ONLY use to close a cycle (e.g. topology A→B→C→A). Do NOT use in pure tree structures (file trees, doc trees, org charts). One free_link per cycle max.
spacing_h (optional): horizontal spacing multiplier 0-10 (default: 1). 0=1 cell gap (60px), 1=2 cells (120px), etc.
spacing_v (optional): vertical spacing multiplier 0-10 (default: 0)
is_write_children (optional): propagate style to children (default: false)
Auto-positioning: when free_links are present, new nodes are auto-positioned using a hierarchical tree layout (retrospective mode). When no free_links, positions stay at default (0,0) and the Flutter client handles layout.
UID and order_index are assigned automatically after existing nodes. All other fields are filled with application defaults.
Args: id_mindmap: Mindmap ID nodes: JSON string — array of simplified nodes
| Name | Required | Description | Default |
|---|---|---|---|
| nodes | Yes | ||
| id_mindmap | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors: appending vs replacing, auto-positioning with free_links, auto-assignment of UID/order_index, and default values. It does not mention rate limits or auth, but for a mutation 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 lengthy but well-structured: purpose sentence, sibling contrast, format, field details, and behavioral notes. It front-loads the key purpose and contrast. Some redundancy exists (e.g., 'append nodes' repeated), but overall it is efficiently organized for a complex tool.
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 an output schema (not shown), return value explanation is unnecessary. The description covers parameter details, auto-assignment, positioning behavior, and free_link constraints. The id_mindmap parameter could use slightly more context, but the overall completeness for a 2-param tool is good.
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 0%, so the description compensates with extensive detail on the nodes parameter: full field list, defaults, constraints on free_links, and positional behavior. The id_mindmap parameter is minimally described as 'Mindmap ID', but that is acceptable for an integer ID.
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 'Append nodes to an existing mindmap (simplified format)' and explicitly contrasts with sync_nodes, which replaces everything. This provides a specific verb+resource and distinguishes it from a sibling 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 contrasts add_nodes with sync_nodes, explaining when to use each. It also provides guidance on free_links usage (only for cycles, not pure trees). While it does not explicitly list when not to use, the contrast and field notes offer adequate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a planning assignment with human-friendly parameters.
This tool builds the JSON payloads internally — you only need to provide dates (YYYY-MM-DD), times (hour/minute integers), and weekday names. It mirrors the Flutter setSingleOutForm / setMultiOutForm logic.
Two modes:
Single-day: start_date == end_date, weekdays omitted or empty. Creates one slot per user on that date.
Recursive: start_date < end_date, weekdays specifies which days of the week are active. Creates one slot per user per active weekday.
Args: id_activity: Activity ID (from list_activities) user_ids: List of user IDs to assign (from activity participants) titre: Assignment title (e.g. "Morning shift") start_date: Start date in YYYY-MM-DD format (e.g. "2026-06-23") end_date: End date in YYYY-MM-DD format. For single-day, use same as start_date. start_hour: Start hour 0-23 (e.g. 8 for 08:00) start_minute: Start minute 0-59 (e.g. 0) end_hour: End hour 0-23 (e.g. 14 for 14:00) end_minute: End minute 0-59 (e.g. 0) weekdays: Active weekday names for recursive mode. Case-insensitive. Full names or 3-letter abbreviations: monday/mon, tuesday/tue, etc. Omit or leave empty for single-day assignment. notes: Optional notes text
Returns: JSON string — human-readable summary with group ID, slot count, and per-slot details (slot_id, day_of_year, user_id, times).
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | ||
| titre | Yes | ||
| end_date | Yes | ||
| end_hour | Yes | ||
| user_ids | Yes | ||
| weekdays | No | ||
| end_minute | Yes | ||
| start_date | Yes | ||
| start_hour | Yes | ||
| id_activity | Yes | ||
| start_minute | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 builds JSON payloads internally, mirrors Flutter logic, and returns a human-readable JSON summary. However, it does not mention idempotency, conflict handling, or permission requirements, which are relevant for a create 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?
The description is well-structured with sections, bullet points for modes, and a clean args list. Every sentence adds value; there is no fluff or redundancy. The length is justified by the tool's complexity (11 parameters).
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 11 parameters, two modes, and an output schema, the description covers all necessary aspects: parameter formats, mode logic, return value structure (JSON string with group ID and per-slot details). It is fully complete for an agent to invoke 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 description coverage is 0%, so the description must compensate. It thoroughly documents each parameter with formats (YYYY-MM-DD, hour/minute integers), examples, and behavioral context (e.g., weekdays case-insensitive, omit for single-day). This adds immense value beyond the bare 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 it creates a planning assignment with human-friendly parameters and explains two modes (single-day vs recursive). Although sibling 'add_assignment' exists, the description does not explicitly differentiate when to use this versus alternatives, but the purpose is specific and well-articulated.
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 conditions for using single-day vs recursive modes (based on date equality), but it does not guide when to use this tool over alternatives like 'add_assignment' or 'modify_assignment'. In a context with many sibling tools, this omission reduces guidance for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an assignment group and all its time slots.
Removes the recursive group and every slot that references it. Use get_activity first to find the group ID.
Args: id_activity: Activity ID delete_recursive_group_slot: Group ID to delete
Returns: JSON string — server confirmation.
| Name | Required | Description | Default |
|---|---|---|---|
| id_activity | Yes | ||
| delete_recursive_group_slot | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description fully bears transparency burden. It discloses cascading deletion: 'Removes the recursive group and every slot that references it.' This is key behavioral context beyond the basic operation. Could mention irreversibility 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?
Description is brief, front-loaded with purpose, then parameters, then return value. Every sentence adds value with no redundancy. Well-structured for agent parsing.
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 params, output schema exists), the description covers key aspects: action, effect (cascading deletion), prerequisite, parameters, and return type. Could mention error handling or irreversibility, but overall complete for its scope.
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 0% description coverage. Description adds basic meaning: id_activity is 'Activity ID', delete_recursive_group_slot is 'Group ID to delete'. This clarifies purpose but lacks detail on why both are needed or expected value ranges.
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 deletes an assignment group and all its time slots. It uses specific verbs and identifies the resource. Among sibling tools, it is distinct from delete_node, delete_message, and other assignment operations.
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 prerequisite: 'Use get_activity first to find the group ID.' This guides the agent on necessary prior steps. No exclusion or alternative tools mentioned, 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.
Delete a bot message.
Removes a message sent by the bot. Only bot messages can be deleted with this tool (use the user API for user messages).
Args: delete_message_id: Message ID to delete
Returns: JSON string — server confirmation.
| Name | Required | Description | Default |
|---|---|---|---|
| delete_message_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states it deletes and returns confirmation, but does not explicitly mention irreversibility or permission requirements. The restriction to bot messages is a useful behavioral trait, but more detail could be added.
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 three sentences for the main function, plus structured Args and Returns sections. It is front-loaded with the core purpose and efficiently uses space 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?
The tool is simple with one parameter, and the description covers purpose, usage conditions, parameter, and return format. It is mostly complete; mentioning irreversibility would improve it further.
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 0%, so the description must compensate. It adds a brief explanation for 'delete_message_id' ('Message ID to delete'), which clarifies the parameter's purpose but lacks format or constraints 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?
Clearly states 'Delete a bot message' with specific verb and resource. Differentiates from sibling tools by specifying only bot messages can be deleted, which distinguishes it from other delete or update 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?
Explicitly provides when to use (bot messages) and when not to use (user messages), with an alternative ('use the user API for user messages'). This gives clear guidance for the AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a single node and its entire subtree from a mindmap.
This is the SAFE way to delete a node. It reads the full mindmap, removes the target node and all its descendants, cleans free_links pointing to deleted nodes, and syncs the remaining nodes back.
The root node (parent=0) cannot be deleted — returns an error.
The algorithm mirrors the Flutter client's MindMapManager._deleteNodeRecursive:
Recursively collect all descendant order_indexes
Clean free_links in remaining nodes that point to deleted nodes
Remove all deleted nodes in one pass
Sync the remaining nodes back
Args: id_mindmap: Mindmap ID order_index: Order index of the node to delete (1-based)
| Name | Required | Description | Default |
|---|---|---|---|
| id_mindmap | Yes | ||
| order_index | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavior: recursive subtree deletion, cleaning of free_links, and that the root node cannot be deleted. It also references the algorithm steps, offering deep 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 well-structured with a concise first-line summary followed by detailed sections. It is efficient but includes algorithm steps that, while informative, could be slightly trimmed for tighter focus.
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 key aspects: what it does, constraints, algorithm details. An output schema exists but is not referenced, and lack of mention about idempotency or node existence handling is a minor gap. Overall, it is sufficiently complete for a deletion 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 0%, so the description compensates by explaining that 'order_index' is 1-based and that 'id_mindmap' is the mindmap ID. While the schema provides types, the description adds semantic meaning beyond the bare property titles.
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 'Delete a single node and its entire subtree from a mindmap' with a specific verb, resource, and context. It distinguishes from sibling tools like delete_assignment or delete_message by focusing on mindmap nodes and noting the subtree deletion.
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 labels this as 'the SAFE way to delete a node' and explains the algorithm, providing context for when to use it. However, it does not explicitly mention alternatives or scenarios where other tools might be preferred (e.g., bulk deletions), though few siblings directly compete with this function.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a specific activity (full metadata).
Returns the full activity object including participants, planning groups, and assignment details. Use list_activities first to find the IDs.
Args: id_activity: Activity ID
Returns: JSON string — full activity metadata object.
| Name | Required | Description | Default |
|---|---|---|---|
| id_activity | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Although no annotations, description clearly indicates read operation ('Read'). Specifies return value (JSON string with full metadata). No contradictions. Could mention auth requirements but acceptable for a simple getter.
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, front-loaded with purpose. Every sentence 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?
For a simple resource retrieval tool, description covers purpose, prerequisite action (list_activities), and output nature. Output schema exists, so return format is fully specified.
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 0%, description adds basic meaning ('Activity ID') but no format or constraints beyond schema. Adequate but minimal compensation.
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?
Explicitly states 'Read a specific activity (full metadata)'. Differentiates from sibling 'list_activities' by advising to use it first to find IDs. Clear verb plus 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?
Provides explicit guidance to use list_activities first to find IDs, indicating when to use this tool. However, lacks explicit when-not or alternative scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read bot messages in a conversation.
Returns messages sent by the bot in the specified conversation. Each message object contains: id, content_message, id_conversation, rel_id_bot, created_datetime, maj_datetime.
Args: id_conversation: Conversation ID
Returns: JSON string — array of bot message objects.
| Name | Required | Description | Default |
|---|---|---|---|
| id_conversation | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It correctly implies read-only behavior but does not mention permissions, rate limits, or any 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?
The description is concise, well-structured with sections for behavior, parameters, and return value. 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 1-parameter read tool with an output schema, the description covers the return fields and identifies the input. It is complete enough for typical use, though pagination or limits are not mentioned.
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 0% description coverage for the parameter, so the description must compensate. It provides a brief but clear definition for id_conversation ('Conversation ID'), adding meaning beyond the schema's type and title.
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 (read) and resource (bot messages in a conversation), and it distinguishes itself from sibling tools like send_message, update_message, delete_message.
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 does not provide guidance on when to use this tool vs alternatives. It only describes what it does, leaving the agent to infer usage context from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a mindmap (full metadata + all nodes).
Returns the complete mindmap object with metadata and a 'nodes' array. Each node has ~25 fields (position, style, title, descriptions, etc.).
⚠️ LARGE RESPONSE: for a mindmap with 60+ nodes and Quill Delta descriptions, the response can exceed 2 MB. Only call this when you actually need to inspect individual nodes. Do NOT use it to verify a previous inject_directory_to_mindmap or replace_mindmap operation — those tools return a summary that is sufficient for validation.
Typical use cases:
Reading node structure before add_nodes or update_nodes_style
Debugging missing/misplaced nodes
Extracting specific node data
Args: id_mindmap: Mindmap ID
Returns: JSON string — {meta: {...}, nodes: [{...}, ...]}.
| Name | Required | Description | Default |
|---|---|---|---|
| id_mindmap | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behavioral traits: large response size (>2 MB), structure of returned data (metadata + nodes array), and node fields. It warns about performance implications. Lacks explicit read-only hint but 'Read' implies idempotence, which 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 well-structured with a clear opening, a warning block, bulleted use cases, and an Args section. It is concise—every sentence 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?
For a read tool with one parameter and an output schema (indicated by context), the description covers purpose, usage guidelines, behavioral transparency, parameter meaning, and return format. It is complete enough for an 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?
The only parameter id_mindmap is explained as 'Mindmap ID' in the Args section. While the schema defines it as integer with title, the description adds context that it is the identifier for the mindmap. With 0% schema description coverage, this compensation is effective but minimal.
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 'Read a mindmap (full metadata + all nodes).' which provides a specific verb and resource. It distinguishes itself from siblings like get_mindmap_summary and inject_directory_to_mindmap by warning against using it for verification, and lists typical use cases that further clarify its unique role.
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 NOT to use it: 'Do NOT use it to verify a previous inject_directory_to_mindmap or replace_mindmap operation — those tools return a summary that is sufficient for validation.' Also provides typical use cases, giving clear guidance on appropriate contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a compact summary of a mindmap — node count, titles, structure, and whether each node has a description.
Does NOT return full node data, descriptions, positions, or styles. Use this when you need to know how many nodes exist or what the structure looks like, without loading the full (potentially huge) mindmap data.
Args: id_mindmap: ID of the mindmap to summarize.
Returns: JSON string — compact summary with total_nodes, max_depth, estimated_size_kb, and a list of nodes (order_index, title, parent, size_box, has_description).
| Name | Required | Description | Default |
|---|---|---|---|
| id_mindmap | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It confirms a read-only operation, describes return format, and sets expectations. Lacks mention of auth or rate limits, but for a simple read 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?
Concise and well-structured: first sentence states core purpose, then clarifies scope, then lists args and returns. No redundant information; 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 all relevant aspects: what tool does, what it doesn't, when to use, parameter meaning, and return structure. With a single required parameter and an output schema, description is complete and self-sufficient.
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?
Only one parameter (id_mindmap). Description explains its purpose as 'ID of the mindmap to summarize,' adding meaning beyond the schema's type/title. Schema has 0% description coverage, so description compensates effectively.
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 reads a compact summary of a mindmap, specifying the exact content (node count, titles, structure, has_description). Distinguishes from tools like get_mindmap by mentioning what it does NOT return.
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 tells when to use (when you need node count/structure without loading full data) and what to avoid (does NOT return full node data). Provides a clear use case and differentiates from alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the description of a single node in a mindmap by its order_index.
Returns the description text (Quill Delta JSON) for that specific node. Use this after get_mindmap_summary to read the content of a specific node without loading the entire mindmap. The description is capped at ~4 KB.
Args: id_mindmap: ID of the mindmap. order_index: Order index of the node to read (1-based).
Returns: JSON string — {id_mindmap, order_index, title, description} or {error: "Node with order_index=X not found in mindmap Y"}.
| Name | Required | Description | Default |
|---|---|---|---|
| id_mindmap | Yes | ||
| order_index | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses the read-only nature, return format (JSON with specific fields), error case, and a 4 KB cap. This is thorough 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?
Four well-structured sentences plus an Args list. Front-loaded with purpose, followed by usage and details. No redundant or missing information. Could be slightly more compact but 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 simplicity (2 params, read-only) and the presence of an output schema, the description fully covers purpose, usage, parameters, return format, error handling, and size limit. Nothing essential is missing.
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 0% with no descriptions, but the description compensates by explaining id_mindmap as 'ID of the mindmap' and order_index as '1-based', adding meaning beyond the raw schema types.
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 'Read', the resource 'description of a single node', and the method 'by its order_index'. It distinguishes itself from siblings like get_mindmap_summary and get_mindmap by specifying a single node retrieval.
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 using this after get_mindmap_summary to avoid loading the entire mindmap, providing clear context. Does not explicitly list when not to use, but the guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan a directory, read file contents, and inject everything into a mindmap.
This is a one-shot tool: it scans the directory tree, reads each file's content, converts it to Quill Delta JSON (for .md/.markdown/.txt files), builds the full node hierarchy, and syncs it to the mindmap via sync_nodes.
The AI does NOT need to manipulate JSON — everything happens internally.
RECOMMENDED WORKFLOW:
Call tree_scope on the same path to get a reference count.
Call inject_directory_to_mindmap with the same path + id_mindmap.
Compare the returned summary (total_nodes, descriptions_filled) with the tree_scope count. If they match and errors is empty, the injection is validated — do NOT call get_mindmap to re-verify.
File handling by extension:
.md / .markdown → content converted via markdown_to_quill_delta()
.txt → content wrapped as plain text Quill Delta
.docx, .pdf, .xlsx, images, binaries, etc. → node created, description empty
Unknown extensions → node created, description empty
Files > 500 KB → node created, description empty (too large)
The 'descriptions' field on each node is a Quill Delta JSON string. Directory nodes (categories) never get descriptions — only file leaves do.
Args: root_path: absolute path to the directory to scan root_title: title for the root node (empty = use directory name) id_mindmap: target mindmap ID to inject the nodes into
Returns: JSON string with a summary: {"status": "success", "total_nodes": N, "descriptions_filled": N, "files_ignored": N, "total_desc_size_kb": N, "errors": [], "ignored_formats": [".docx", ".pdf", ...]}
| Name | Required | Description | Default |
|---|---|---|---|
| root_path | Yes | ||
| id_mindmap | No | ||
| root_title | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description fully explains behavior: one-shot operation, internal JSON conversion, file handling by extension, size limit (500 KB), and that directory nodes get no descriptions. It is transparent about what happens internally.
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 well-structured with sections (intro, workflow, file handling, args, returns). However, it is somewhat lengthy; some detail could be streamlined without losing 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?
Given the tool's complexity (directory scanning, multiple file types, output summary), the description is comprehensive. It covers file handling, parameter defaults, workflow, return format with example, and error indication. Output schema exists, so return format is covered.
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 0%, but the description adds full meaning: root_path (absolute path), root_title (defaults to directory name), id_mindmap (default 0). It clarifies each parameter's role 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 scans a directory, reads files, and injects content into a mindmap. It specifies the verb-resource combination and distinguishes from sibling tools like tree_scope and sync_nodes.
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 includes a recommended workflow (call tree_scope first, then inject, compare results) and explicitly advises against calling get_mindmap for verification. It also details file handling rules for when to create nodes with descriptions vs empty.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List activities where the bot is assigned (metadata only).
Returns a JSON string. The response contains an array of activity objects with at least: id, titre, participants (list of user IDs), and scheduling metadata. Use get_activity to read the full detail of a single activity.
Returns: JSON string — array of activity metadata objects.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It states the operation is non-destructive (listing) and describes the return format. However, it omits details like pagination, rate limits, or whether the bot's assignment is fixed, leaving 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?
The description is concise with three sentences: purpose, return format, and alternative reference. It is front-loaded and every sentence adds value, making it 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?
Given zero parameters and an output schema describing return fields, the description covers the essential aspects. It references 'get_activity' for completeness, but could mention if metadata includes timestamps or status.
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 schema coverage is 100%. The description does not need to add parameter details. The baseline score of 4 is appropriate as it correctly reflects the lack of 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's purpose: listing activities where the bot is assigned, and specifies it returns metadata only. It distinguishes itself from 'get_activity' which provides full detail, making the purpose precise and actionable.
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 recommends using 'get_activity' for full details of a single activity, giving clear context for when to use this tool versus an alternative. However, it does not mention when not to use this tool or address other sibling tools like 'list_mindmaps'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List mindmaps where the bot is assigned (metadata only).
Returns a JSON string with an array of mindmap metadata: id, titre, rel_id_user, participants, bots, canvas dimensions, type_mindmap, created_datetime, maj_datetime. Does NOT include nodes — use get_mindmap to read the full node tree of a specific mindmap.
Returns: JSON string — array of mindmap metadata objects.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 the return type ('JSON string'), the scope ('metadata only'), and lists the fields included. However, it does not mention potential pagination, ordering, or authentication requirements, which is a minor 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?
The description is extremely concise: two sentences plus a return type clause. The main purpose is front-loaded, and every sentence adds essential 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?
Given the tool's simplicity (no parameters), the description adequately covers the core behavior. It describes output fields and distinguishes from get_mindmap. However, it lacks details on potential edge cases (e.g., empty result, maximum items) that could be relevant for an agent.
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, and schema coverage is 100% (trivially). The description does not need to elaborate on parameters. The baseline for zero parameters is 4, and the description meets that standard by focusing on the output.
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 'List mindmaps where the bot is assigned (metadata only)', providing a specific verb and resource. It distinguishes itself from the sibling tool 'get_mindmap' by explicitly stating that nodes are not included.
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 the agent when not to use this tool ('Does NOT include nodes') and directs to an alternative ('use get_mindmap to read the full node tree'). This provides clear guidance on selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Modify an existing assignment group with human-friendly parameters.
Replaces the group definition and all its time slots. The server marks a tombstone for the old group, removes old slots, and creates new ones. Uses the same parameter format as create_assignment but requires group_id.
Args: id_activity: Activity ID group_id: Existing group ID to update (from get_activity or create_assignment result) user_ids: List of user IDs to assign titre: Assignment title start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format (same as start_date for single-day) start_hour: Start hour 0-23 start_minute: Start minute 0-59 end_hour: End hour 0-23 end_minute: End minute 0-59 weekdays: Active weekday names for recursive mode. Omit for single-day. notes: Optional notes text
Returns: JSON string — human-readable summary with updated slot details.
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | ||
| titre | Yes | ||
| end_date | Yes | ||
| end_hour | Yes | ||
| group_id | Yes | ||
| user_ids | Yes | ||
| weekdays | No | ||
| end_minute | Yes | ||
| start_date | Yes | ||
| start_hour | Yes | ||
| id_activity | Yes | ||
| start_minute | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses internal behavior: 'marks a tombstone for the old group, removes old slots, and creates new ones.' This gives clear insight into destructive, replacement nature.
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?
Well-structured with explicit purpose, behavioral note, parameter list, and return value. Slightly verbose due to full parameter list, but still efficient and readable.
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, behavior, all parameters, and return type. Output schema exists, so return explanation is sufficient. Missing error scenarios or prerequisites (e.g., permissions), but adequate 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 has 0% description coverage, but the description includes an Args block that explains all 12 parameters with clear descriptions, fully compensating for the schema gap.
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 'Modify an existing assignment group' with a specific verb and resource. Notes similarity to create_assignment, but does not explicitly differentiate from sibling update_assignment, leaving some ambiguity.
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 that it replaces the entire group definition and time slots, implying full updates. Mentions parameter format similarity to create_assignment, but lacks explicit when-to-use or when-not-to-use guidance and does not compare to update_assignment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read all planning slots for a given year via the bot API.
Returns actual time slot data (start_time, end_time, day of year, user assignments) and group controls (recursive assignment groups).
Args: year: Year to read (e.g. 2026). Returns all slots for that year. id_activity: Optional — filter to a specific activity. 0 = all activities.
Returns: JSON string — a readable report with: - Per-activity summary: activity_id, group_title, date_range, active_weekdays, slots: [{day_of_year, user_id, start_time, end_time}] - If id_activity is 0, all activities are included. - If id_activity is set, only that activity's slots are returned.
Workflow: 1. Call list_activities to get activity IDs 2. Call read_planning(year=2026) to get all slots 3. Filter by activity or user as needed
| Name | Required | Description | Default |
|---|---|---|---|
| year | Yes | ||
| id_activity | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It comprehensively describes the return format (JSON with per-activity summary, slots, etc.) and parameter effects. It does not mention side effects, but as a read-only tool this is acceptable. No contradictions.
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 well-structured and concise. It starts with the core purpose, then details the return format, and ends with a workflow. Every sentence adds value without redundancy. Appropriate length for the tool's complexity.
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 that an output schema exists (not shown but indicated), the description aligns well by explaining the return structure. All necessary information is covered: parameters, return format, and usage workflow. No gaps are evident.
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 explains both parameters in detail: year (example 2026, returns all slots for that year) and id_activity (optional, 0 means all activities). This adds significant meaning beyond the input schema, which only provides types and defaults. Schema coverage is 0%, but the description fully compensates.
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: 'Read all planning slots for a given year via the bot API'. It specifies the resource (planning slots), the verb (read), and the context (year). This distinguishes it from sibling tools which handle assignments, nodes, or mindmaps.
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 includes a 'Workflow' section that advises calling list_activities first and then filtering, providing practical guidance. It explains the optional id_activity parameter and its behavior. However, it does not explicitly state when not to use the tool or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace all nodes in a mindmap (simplified format).
Removes existing nodes and replaces them with the new set. The first node must have parent=0 (it becomes the root).
Simplified format (JSON string): [ {"title": "Root", "parent": 0, "color": "0xFFF0BA6D", "size_box": 2}, {"title": "Category A", "parent": 1, "color": "0xFF7A8FF5", "size_box": 1}, {"title": "Item 1", "parent": 2, "color": "0xFF7A8FF5"}, {"title": "Item 2", "parent": 2} ]
Fields:
title (required): node title
parent (required): order_index of the parent (0 = root, 1 = first node)
color (optional): hex color (default: 0xFF7A8FF5)
pos_x, pos_y (optional): canvas position (default: 0)
size_box (optional): 0=normal, 1=category, 2=root (default: 0)
bold, italic, underline (optional): text style
line_type (optional): 0=curve, 1=rounded, 2=square
line_style (optional): 0=solid, 1=dashed
stroke_width, dot_radius, radius, border_size, label_size (optional)
icon_id (optional): icon ID
active_bg_colors (optional): active background colors
descriptions (optional): descriptive text
free_links (optional): list of order_index for free links. ONLY use to close a cycle (e.g. topology A→B→C→A). Do NOT use in pure tree structures (file trees, doc trees, org charts). One free_link per cycle max.
spacing_h (optional): horizontal spacing multiplier 0-10 (default: 1). 0=1 cell gap (60px), 1=2 cells (120px), etc.
spacing_v (optional): vertical spacing multiplier 0-10 (default: 0)
is_write_children (optional): propagate style to children (default: false)
Auto-positioning: when free_links are present, nodes are auto-positioned using a hierarchical tree layout (retrospective mode). When no free_links, positions stay at default (0,0) and the Flutter client handles layout.
UID and order_index are assigned automatically (1, 2, 3...). All other fields are filled with default values.
Args: id_mindmap: Mindmap ID nodes: JSON string — array of simplified nodes
| Name | Required | Description | Default |
|---|---|---|---|
| nodes | Yes | ||
| id_mindmap | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes destructive behavior (removes existing nodes), auto-positioning logic, free_links constraints, and default value handling. No annotations provided, so description carries full burden.
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?
Well-structured with a clear example, field list, and behavioral notes. Slightly long but each section adds value; front-loaded with the core 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?
Covers all relevant aspects: replacement behavior, node format, field semantics, auto-positioning, and free_links rules. Output schema exists (context signal) but not mentioned; still complete enough.
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 0%, but description extensively documents the JSON string format, all fields, defaults, and constraints, fully compensating for the lack of parameter info 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 clearly states 'Replace all nodes in a mindmap' and 'Removes existing nodes and replaces them with the new set,' which distinguishes it from sibling tools like add_nodes (additive) and delete_node (single node 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?
Provides explicit constraints (first node must have parent=0, free_links usage rules) and auto-positioning behavior, but does not explicitly compare to alternatives like add_nodes or sync_nodes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a message to a conversation as the bot.
The message is sent on behalf of the bot assigned to the conversation. Content is plaintext — the server encrypts it before storage.
Args: content_message: Message content (plaintext, encrypted server-side) id_conversation: Conversation ID (0 = broadcast to all assigned conversations)
Returns: JSON string — server confirmation with message ID.
| Name | Required | Description | Default |
|---|---|---|---|
| content_message | Yes | ||
| id_conversation | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description discloses that message is sent on behalf of bot, plaintext with server-side encryption, and special broadcast behavior for id_conversation=0. Returns JSON with message ID.
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?
Description is well-organized with sections (Args, Returns) and no unnecessary information. 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?
Given 2 parameters, 0% schema coverage, and presence of output schema (mentioned but not shown), the description adequately covers bot behavior, encryption, broadcast, and return value.
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 0% description coverage. The description adds meaningful info: content_message is plaintext encrypted server-side, id_conversation defaults to 0 meaning broadcast to all conversations.
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 'Send a message to a conversation as the bot', using a specific verb and resource. It distinguishes from sibling tools like delete_message and update_message.
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 (as bot) but does not explicitly state when to use this tool vs alternatives like update_message or delete_message, nor provides exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sync mindmap nodes (Redis only + dirty flag).
⚠️ DESTRUCTIVE: replaces ALL nodes. If you send 1 node out of 99, the other 98 are deleted. Always send the COMPLETE node list.
The cron flushDirtyMindmaps handles database persistence. This is the same flow used by the Flutter client.
Args: id_mindmap: Mindmap ID nodes: JSON string — array of full node objects (advanced use)
| Name | Required | Description | Default |
|---|---|---|---|
| nodes | Yes | ||
| id_mindmap | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses the destructive behavior, the replacement of all nodes, and the Redis-only dirty flag mechanism. It also explains the persistence flow via cron, providing clear behavioral context for the agent.
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 and well-structured, starting with the key warning and behavioral context in the first few lines, followed by a clear argument list. Every sentence serves a purpose 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 tool's destructive nature and the presence of an output schema, the description provides comprehensive guidance: the destructive behavior, the need for complete node list, the argument details, and the backend persistence mechanism. This allows the agent to correctly select and invoke the 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 description adds meaning beyond the schema by explaining that 'nodes' is a JSON string representing an array of full node objects, and calling it 'advanced use'. For 'id_mindmap', it provides a brief description. Since schema coverage is 0%, this adds value, though an example of the JSON format could further clarify.
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 syncs mindmap nodes, specifically 'Redis only + dirty flag', and distinguishes from siblings like add_nodes, delete_node, and update_node by explaining it replaces the entire node list. The verb 'sync' with resource 'mindmap nodes' is specific and differentiated from other node manipulation 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 explicitly warns that the tool is destructive, replacing all nodes, and advises to always send the complete node list. It also mentions the cron flushDirtyMindmaps for persistence, implying when to use this tool (full sync) versus alternatives like add_nodes or update_node for partial updates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan a directory and return compact telemetry (no file content).
Returns a JSON array where each entry is: {title, type, size, oi, parent, depth}
type: "dir", "file", or "root"
size: human-readable for files (e.g. "2.3KB"), item count for dirs
oi: 1-based order_index (matches what tree_to_mindmap would produce)
parent: order_index of the parent node
depth: nesting level (0 = root's direct children)
Use this BEFORE inject_directory_to_mindmap to get a reference count of expected nodes (1 root + N dirs + M files). After injection, compare the summary's total_nodes with this count to validate — no need to call get_mindmap afterwards.
Does NOT read file content — just names, sizes, and structure. Hidden files and VCS dirs are skipped automatically.
Args: root_path: absolute path to the directory to scan root_title: title for the root entry (empty = use directory name) max_depth: maximum nesting depth to scan (default 10)
Returns: JSON string — array of compact scope entries.
| Name | Required | Description | Default |
|---|---|---|---|
| max_depth | No | ||
| root_path | Yes | ||
| root_title | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears the full burden of disclosing behavior. It discloses that the tool does not read file content, skips hidden files and VCS dirs, and returns a JSON array with specific fields. There is no mention of side effects or destructive actions, which is appropriate for a read-only scan. The output structure is thoroughly explained.
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 well-structured: a summary sentence, then output format details, usage guidance, and parameter descriptions. It is front-loaded with the main purpose. While somewhat lengthy, each sentence adds value and is clearly organized. Minor redundancy could be trimmed, but overall it's 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 that an output schema exists, the description still provides detailed explanation of the return value, including field names, types, and semantics. It covers scanning behavior (skipping hidden files, depth limit) and usage context. No critical information is missing for an agent to select and invoke 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?
Since schema description coverage is 0%, the description must compensate. It explains root_path as an absolute path, root_title as the title for the root entry (with default behavior: empty uses directory name), and max_depth as maximum nesting depth with default 10. This adds meaning beyond the schema types and 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?
The description clearly states that the tool scans a directory and returns compact telemetry without reading file content. It distinguishes itself from sibling tools like inject_directory_to_mindmap by specifying its use case as a precursor for node count validation.
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 recommends using this tool before inject_directory_to_mindmap to obtain a reference count of expected nodes and after injection to validate totals. It also notes that hidden files and VCS directories are skipped. However, it does not provide explicit 'when not to use' guidance, 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.
Scan a directory tree and return a JSON array of simplified mindmap nodes.
The returned JSON is ready to use with replace_mindmap or add_nodes. Order_index is implicit (1-based position in the array). Parent values are pre-computed — no manual index tracking needed.
Directories become category nodes (size_box=1), files become leaf nodes. Hidden files, VCS dirs (.git, .github, pycache, node_modules, etc.) are skipped automatically.
Args: root_path: absolute path to the directory to scan root_title: title for the root node (empty = use directory name)
Returns: JSON string — array of simplified nodes ready for replace_mindmap.
| Name | Required | Description | Default |
|---|---|---|---|
| root_path | Yes | ||
| root_title | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description effectively discloses key behaviors: directories become category nodes, files become leaf nodes, hidden files and VCS directories are automatically skipped, order_index is implicit, and parent values are pre-computed. It also clarifies the return format. This provides good transparency, though it does not mention error handling or path validation.
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 and well-structured, with a clear hierarchy: purpose, integration hints, behavioral details, parameter explanations, and return value. Every sentence adds value, and the information is front-loaded. No redundant or tautological statements.
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 and the existence of an output schema, the description adequately covers scanning behavior, node categorization, hidden file handling, parameters, and integration. It does not detail the exact structure of the output nodes (since output schema exists) and could mention error conditions, but overall it is sufficiently 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?
The description adds significant meaning beyond the input schema: it explains that root_path is an absolute path and root_title when empty uses the directory name. Since schema coverage is 0%, this compensation is crucial. It clarifies the purpose of each parameter and their effects, though it lacks details on validation or default behavior beyond the empty string case.
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: scanning a directory tree and returning a JSON array of simplified mindmap nodes. It includes specific details about the output being ready for use with sibling tools replace_mindmap and add_nodes, and mentions automatic skipping of hidden files and VCS directories, making the purpose distinct and 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 implies usage context by stating the output is ready for replace_mindmap or add_nodes, but it does not explicitly specify when to use this tool versus the similar sibling inject_directory_to_mindmap or other alternatives. There is no 'when not to use' guidance, leaving room for ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing assignment group and its time slots.
Replaces the group definition and all its slots. Use get_activity first to find the group ID (update_assignement_id). The planning_list and recursive_group formats are identical to add_assignment, but the group id and slot ids should be set to the existing values (non-zero).
Args: id_activity: Activity ID update_assignement_id: Existing group ID to update planning_list: JSON string — full slot list (same format as add_assignment) recursive_group: JSON string — updated group definition (same format, id = group ID)
Returns: JSON string — server response with updated slot IDs.
| Name | Required | Description | Default |
|---|---|---|---|
| id_activity | Yes | ||
| planning_list | Yes | ||
| recursive_group | Yes | ||
| update_assignement_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral transparency. It states 'Replaces the group definition and all its slots', indicating a destructive update, and mentions the return format. However, it omits details on permissions, reversibility, error states, or side effects, leaving significant gaps 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 relatively long but well-structured with a clear introduction and bulleted args. Some redundancy exists (e.g., repeating 'same format as add_assignment'), and the size could be reduced without losing 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?
Given the output schema exists, the description adequately covers the return value. It includes a prerequisite (get_activity) and references sibling formats. However, it does not address failure modes, rollback, or concurrency issues, leaving the agent with incomplete context for safe invocation.
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 0%, so the description must explain each parameter. It lists all four arguments with brief explanations (e.g., 'id_activity: Activity ID', 'planning_list: JSON string — full slot list'). It adds context by referencing identical formats in 'add_assignment'. However, it lacks detailed format specifications or validation rules, which limits its utility.
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 an existing assignment group and its time slots', using a specific verb and resource. It distinguishes from 'add_assignment' by noting the use of existing IDs, but does not fully differentiate from 'modify_assignment' or 'delete_assignment'.
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 'Use get_activity first to find the group ID' and explains that the JSON formats are identical to 'add_assignment'. However, it does not provide explicit when-to-use versus alternatives like 'modify_assignment' or 'delete_assignment', nor does it outline 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.
Update a bot message.
Replaces the content of an existing bot message. Only messages sent by the bot can be updated (use user_send_message for user messages).
Args: update_message_id: Message ID to update content_message: New content (plaintext)
Returns: JSON string — server confirmation.
| Name | Required | Description | Default |
|---|---|---|---|
| content_message | Yes | ||
| update_message_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description covers core behavior (replaces content, bot-only constraint, returns JSON confirmation). However, it lacks details on error handling, permissions, or idempotency, 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?
The description is succinct with a clear intro, a usage note, parameter list, and return 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?
For a simple update tool with two parameters and an output schema, the description covers the main purpose, parameters, and return. It lacks information on error conditions or prerequisites, but is largely adequate.
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 0%, but the description provides brief descriptions for both parameters ('Message ID to update' and 'New content (plaintext)'), adding meaning beyond schema titles and types. It does not specify constraints like length limits.
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 a bot message' and 'Replaces the content of an existing bot message.' It distinguishes from user messages by referencing 'user_send_message' tool for user messages.
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 that only bot-sent messages can be updated and suggests using 'user_send_message' for user messages, providing clear guidance on when to use and 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.
Update a single node in a mindmap — all fields supported, no data loss.
This is the SAFE way to modify any field of a single node. It reads the full mindmap, applies targeted changes to one node, and syncs everything back. Other nodes (including their descriptions) are preserved untouched.
Unlike sync_nodes (which replaces ALL nodes and can destroy data), this tool only touches the specified node. Use it for:
Renaming a node (title)
Updating a node's description (markdown → Quill Delta conversion)
Changing the parent (re-parenting, with cycle detection)
Moving a node (pos_x, pos_y)
Changing any style field (color, bold, size_box, etc.)
Updating free_links
node_updates is a JSON string with any combination of fields: { "title": "New title", // string — new node title "descriptions": "markdown text", // string — markdown converted to Quill Delta "parent": 2, // int — new parent order_index (0 = root) "color": "0xFFFF6F91", // hex color string "pos_x": 240, // canvas X position "pos_y": 480, // canvas Y position "is_manual_position": true, // bool — preserve position "size_box": 1, // 0=normal, 1=category, 2=root, 3-11=larger "bold": true, // bool "italic": false, // bool "underline": false, // bool "line_type": 1, // 0=curve, 1=rounded, 2=square "line_style": 0, // 0=solid, 1=dashed "stroke_width": 2.5, // float "dot_radius": 6, // float "radius": 5, // int "border_size": 2, // int "label_size": 12, // float "icon_id": 0, // int "active_bg_colors": false, // bool "spacing_h": 2, // 0-10 "spacing_v": 0, // 0-10 "is_write_children": true, // propagate style to children (one-shot) "free_links": [3, 5] // list of order_indexes }
Only provided fields are updated — others remain untouched. Setting pos_x or pos_y automatically sets is_manual_position=true. Descriptions are converted from markdown to Quill Delta by the algorithm.
Args: id_mindmap: Mindmap ID order_index: Order index of the node to update (1-based) node_updates: JSON string with fields to update
| Name | Required | Description | Default |
|---|---|---|---|
| id_mindmap | Yes | ||
| order_index | Yes | ||
| node_updates | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description discloses that it reads the mindmap, applies targeted changes, preserves other nodes, includes cycle detection for re-parenting, markdown-to-Quill conversion, and only updates provided fields.
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 well-structured with a clear summary, bullet-point use cases, and a JSON example. Every sentence 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?
The description covers all necessary context: purpose, usage, parameters, behavior, and contrasts with siblings. Output schema exists but is not required to be explained here.
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?
With 0% schema description coverage, the description compensates by detailing the node_updates JSON format comprehensively, listing all possible fields with types and descriptions, and explaining order_index is 1-based.
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 updates a single node in a mindmap with all fields supported, no data loss, and explicitly distinguishes from sync_nodes which replaces all nodes.
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?
It provides explicit use cases (renaming, updating description, re-parenting, moving, style changes, free_links) and contrasts with sync_nodes as an alternative for bulk replacement, guiding when 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.
Update style fields on specific nodes without losing existing data.
This is the SAFE way to modify node style — it reads the full mindmap, applies targeted changes, and syncs everything back. Never use sync_nodes with a partial node list (it deletes everything not sent).
style_updates is a JSON string: { "node_indices": [1, 2, 3], // order_index of nodes to update (empty = all) "size_box": 0, // optional: 0=normal(180×60), 1=category(180×120), 2=root(180×180), 3-11=larger paliers "line_type": 1, // optional: 0=curve, 1=rounded, 2=square "line_style": 0, // optional: 0=solid, 1=dashed "spacing_h": 2, // optional: horizontal spacing multiplier (0-10) "spacing_v": 0, // optional: vertical spacing multiplier (0-10) "color": "0xFF7A8FF5", // optional: hex color "bold": true, // optional "italic": false, // optional "underline": false, // optional "stroke_width": 2.5, // optional "dot_radius": 6, // optional "radius": 5, // optional "border_size": 2, // optional "label_size": 12, // optional "icon_id": 0, // optional "active_bg_colors": false, // optional "is_write_children": true, // optional: propagate style to children }
Only provided fields are updated — others remain untouched. If node_indices is empty, the update applies to ALL nodes.
Args: id_mindmap: Mindmap ID style_updates: JSON string with node_indices + fields to update
| Name | Required | Description | Default |
|---|---|---|---|
| id_mindmap | Yes | ||
| style_updates | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description discloses the read-modify-write process, that only provided fields are updated, and the safe behavior. Lacks permissions or rate limits, 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?
Description is comprehensive but well-structured with a JSON example and headings. Could be slightly more concise, but front-loaded and organized.
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 output schema exists and only 2 parameters, the description covers all necessary context: purpose, usage, parameter details, and behavioral nuances. Complete for this 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 0%, but description provides a detailed JSON example for style_updates with each field's meaning and optionality. This adds immense value beyond the minimal 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 'Update style fields on specific nodes without losing existing data' and distinguishes itself from sync_nodes by warning against using it with partial node lists. Verb and resource 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?
Explicit guidance: 'This is the SAFE way to modify node style — it reads the full mindmap, applies targeted changes, and syncs everything back. Never use sync_nodes with a partial node list (it deletes everything not sent).' Also explains behavior when node_indices is empty.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify and inspect all assignments for an activity.
Reads the activity metadata and validates that all assignment groups have consistent time slots. Returns a telemetry report with:
Activity info (id, title, participants)
Per-group details (group_id, titre, type, date range, active weekdays)
Per-slot details (slot_id, day_of_year, user_id, start/end times)
Consistency checks (group references, date ranges, weekday matching)
Use this after create_assignment or modify_assignment to confirm the server accepted and stored the assignment correctly.
Args: id_activity: Activity ID to verify
Returns: JSON string — telemetry report with activity, groups, slots, and validation results.
| Name | Required | Description | Default |
|---|---|---|---|
| id_activity | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details that the tool 'Reads the activity metadata and validates that all assignment groups have consistent time slots,' indicating read-only behavior. Given no annotations, this is transparent about its non-destructive nature.
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 well-structured with clear sections (purpose, usage, args, returns) and front-loaded with the main purpose. It is slightly verbose 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?
Given a simple tool with one parameter and an output schema, the description covers purpose, parameters, return format, and context for use. It is fully adequate for effective tool selection and invocation.
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 0%, so the description must explain parameters. It lists 'id_activity: Activity ID to verify,' adding context beyond the schema's title, but it is minimal and could elaborate on the source of the ID.
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 'Verify and inspect all assignments for an activity,' using a specific verb and resource. It differentiates from sibling tools by explicitly recommending use after create_assignment or modify_assignment.
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: 'Use this after create_assignment or modify_assignment to confirm the server accepted and stored the assignment correctly.' It implies when not to use (e.g., for creation or modification), but does not provide explicit exclusions.
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.
v1.0.0add_assignmentadd_nodescreate_assignmentdelete_assignmentdelete_messagedelete_nodeget_activityget_messagesget_mindmapget_mindmap_summaryget_node_descriptioninject_directory_to_mindmaplist_activitieslist_mindmapsmodify_assignmentread_planningreplace_mindmapsend_messagesync_nodestree_scopetree_to_mindmapupdate_assignmentupdate_messageupdate_nodeupdate_nodes_styleverify_assignmentScored across 26 tools
Tools are clearly grouped by domain (mindmap, planning, messaging) with distinct purposes. However, there is potential confusion between add_assignment and create_assignment (both create assignments with different parameter styles) and similarly update_assignment vs modify_assignment. The descriptions help differentiate but the overlap reduces clarity.
Most tools follow a consistent snake_case verb_noun pattern. However, there are multiple verbs for similar operations (add/create, update/modify) which introduces minor inconsistency. Overall, the naming is predictable and readable.
With 26 tools covering two main domains plus messaging, the count is slightly high but still reasonable. Some redundancy exists (duplicate raw and human-friendly versions), but each tool serves a specific use case. The scope fits the server's purpose.
The tool set provides full CRUD coverage for mindmaps, planning assignments, and bot messages. Mindmap tools include bulk import and scanning helpers; planning tools offer both raw and human-friendly operations; messaging covers send, read, update, delete. No obvious gaps in the featured workflows.
MCP server for Gainium — manage trading bots, deals, and balances via AI assistants
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for Argo RPG Platform — connects AI assistants to campaign data via OAuth2
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
