yade-mcp connects AI agents to the YADE discrete element method (DEM) engine, enabling documentation browsing, API search, and simulation execution.
Browse YADE API (yade_browse_api): Navigate 350+ classes hierarchically (categories → classes → details), covering engines, materials, interactions, utilities, and simulation control — ~90% of the Python API.
Search YADE API by keywords (yade_query_api): BM25-ranked keyword search across all API docs to find relevant classes or functions (e.g., "friction material", "gravity engine").
Execute code synchronously (yade_execute_code): Run Python code instantly in the live YADE process for quick queries, state inspection (O.bodies, O.iter), and rapid iterative testing.
Submit async simulation tasks (yade_execute_task): Run long Python scripts asynchronously in the background, receiving a task ID immediately.
Check task status and output (yade_check_task_status): Poll the progress, output, and final status of a submitted async task.
List task history (yade_list_tasks): Browse all previously submitted YADE tasks with pagination.
Interrupt a running task (yade_interrupt_task): Gracefully cancel a running async simulation task by its task ID.
Compatible with multiple MCP clients including Claude Code, Codex CLI, Gemini CLI, and OpenCode.
O.engines += [LLM()] # yet another engine.
yade-mcp connects AI agents to YADE, the open-source discrete element method engine, through the Model Context Protocol. The agent browses the YADE API, runs code in a live YADE session, launches long simulations as background tasks, and reads what you type at the YADE console.
Two documentation tools (no bridge needed) and five execution tools (bridge required):
Tool | Purpose | Bridge |
| Walk the YADE Python class tree | No |
| BM25 keyword search across the API | No |
| Run Python in the live YADE process; returns synchronously | Yes |
| Submit a script as a long-running background task | Yes |
| Inspect a running or finished task (output, status) | Yes |
| Stop a running task at an iteration boundary, or cancel a queued one | Yes |
| List submitted tasks with metadata | Yes |
Related MCP server: itasca-mcp
"Set up a triaxial compression test on a dense packing and plot deviatoric stress against axial strain"
"Build an irregular particle as a level set body and drop it onto a plane"
"The simulation is still running, check the unbalanced force without stopping it"
"Look up how GlobalStiffnessTimeStepper picks the timestep, then add it to this model"
"The command I just typed in the console raised an error, what went wrong?"
"List what was run yesterday and summarize what each task produced"
YADE installed
uv installed. It provides the uvx launcher that agent clients use to run yade-mcp; without it the client reports No such file or directory when starting the server.
An AI agent: Claude Code, Codex CLI, Gemini CLI, or any MCP-capable client
Copy this to your AI agent and let it self-configure:
Fetch and follow this bootstrap guide end-to-end:
https://raw.githubusercontent.com/yusong652/yade-mcp/master/docs/agentic/yade-mcp-bootstrap.md1. Register the MCP server with your agent (use the line for yours):
# Claude Code
claude mcp add yade-mcp -- uvx yade-mcp
# Codex CLI
codex mcp add yade-mcp -- uvx yade-mcp
# Gemini CLI
gemini mcp add yade-mcp uvx yade-mcpOr fill in the MCP config file by hand:
{
"mcpServers": {
"yade-mcp": {
"command": "uvx",
"args": ["yade-mcp"]
}
}
}2. Install the bridge into YADE's Python.
YADE embeds one specific interpreter (the system python3 for the Debian and Ubuntu packages, or the one it was built against). A conda or venv Python is a different interpreter, and a package installed there is invisible to YADE. The reliable way to hit the right one is to install from inside YADE, where sys.executable is that interpreter. In the YADE console:
import sys, subprocess
subprocess.check_call([sys.executable, "-m", "pip", "install", "--user", "yade-mcp-bridge"])Two things can go wrong here:
No module named pip: the interpreter has no pip. Install it with the system package manager, for example sudo apt install python3-pip.
externally-managed-environment (Debian 12, Ubuntu 23.04 and later): pip refuses --user by default. Add "--break-system-packages" after "--user" in the command above.
Then exit and restart YADE so the new package directory is picked up.
The bridge is proposed for inclusion in YADE itself (yade-dev/trunk !1187). Once it ships with YADE, this step goes away and the bridge starts with from yade import mcpbridge.
3. Start the bridge in the YADE console:
import yade_mcp_bridge
yade_mcp_bridge.start()It prints one line: YADE MCP Bridge on http://localhost:9002, log: <cwd>/.yade-mcp/bridge.log.
Restart your AI agent and ask it to check that it is connected to YADE. It calls yade_execute_code; ok: true in the response means the whole chain works.
Once first-time setup is done, each new YADE session only needs the bridge started again. In the YADE console:
import yade_mcp_bridge
yade_mcp_bridge.start()The MCP client config persists.
The bridge listens on 9002 by default. To use another port, pass it to start():
yade_mcp_bridge.start(port=9008)The MCP server connects to 9002 unless told otherwise, so register it with the matching URL:
{
"mcpServers": {
"yade-mcp": {
"command": "uvx",
"args": ["yade-mcp", "--bridge-url", "http://localhost:9008"]
}
}
}When YADE runs inside a container, bind the bridge to all interfaces so it is reachable from outside:
yade_mcp_bridge.start(host="0.0.0.0")Publish the port when starting the container (for Docker, -p 9002:9002).
Live REPL in the running YADE process: yade_execute_code runs Python in the session's own namespace, so state persists between calls. It keeps working while a task runs, for reading intermediate results without stopping the simulation.
Task lifecycle: submit a script as a background task, tail its output, stop it at an iteration boundary, fix and resubmit. Tasks queue up and run one at a time, so a multi-stage pipeline can be submitted in one go.
Task history across sessions: every task's script, output, and final state stay on record. A new agent session lists what was run and picks up without being told.
Console input reaches the agent: lines you type at the YADE console arrive in the agent's context on its next call, so you can work at the console and with the agent at the same time.
API documentation without a bridge: the class tree and a BM25 search over the YADE Python API work offline, from a corpus refreshed against current YADE releases.
Multi-client: works with Claude Code, Codex CLI, Gemini CLI, GitHub Copilot CLI, OpenCode, toyoura-nagisa, and other MCP clients.
See Troubleshooting in the bootstrap guide.
See CONTRIBUTING.md for development setup and guidelines.
MIT, see LICENSE.
Browse YADE's Python API as a YADE-native class tree.
The tree is rooted in YADE's real inheritance hierarchy: paths mirror the class's mro up to its category root. No shortcuts — always drill through parents.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Dot-separated path into YADE's class hierarchy. Navigation is tree-driven (no class-name shortcuts). - None or '': list top-level categories (engine / functor / material / shape / ...) - 'engine': list direct sub-trees of Engine (Dispatcher, GlobalEngine, PartialEngine, ...) - 'engine.GlobalEngine': list GlobalEngine's sub-trees (BoundaryController, Collider, PeriodicEngine, ...) plus its direct leaf classes (NewtonIntegrator, InteractionLoop, ...) - 'engine.GlobalEngine.NewtonIntegrator': full docs for NewtonIntegrator - 'functor.LawFunctor.Law2_ScGeom_FrictPhys_CundallStrack': full docs for a contact law functor Every leaf is reached via its parent-class chain. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It states 'no shortcuts' and 'always drill through parents,' which is a behavioral constraint. As a browse tool, it is implicitly read-only, but this is not explicitly stated.
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, consisting of two informative sentences. It is front-loaded with the main purpose. Could include a bit more detail, but overall 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 (one parameter, browse-only) and the presence of an output schema, the description is complete enough. It explains the hierarchy and navigation rules. Minor omission: does not mention the response format, but output schema covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already provides detailed parameter semantics with examples. The tool description adds context about the tree structure, but the parameter description in the schema is sufficiently rich.
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 browses YADE's Python API as a class tree, and the parameter description further clarifies navigation. It is distinct from sibling tools which are task/execution related.
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 explicitly state when to use this tool vs alternatives. However, the siblings are clearly different in function, so the context provides implicit usage guidance. No exclusions or when-not-to-use are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check status and output for a submitted YADE task.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Output lines per page | |
| filter | No | Only keep output lines containing this text | |
| task_id | Yes | Task ID returned by yade_execute_task | |
| skip_newest | No | Skip N newest output lines before pagination | |
| wait_seconds | No | Long-poll: return when the task changes state or after this many seconds. 0 = immediate. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It implies a read-only status check but never states that it is non-destructive or requires no auth, and it says nothing about the long-polling semantics, pagination, or filtering behavior that materially affect how the agent should call it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single efficient sentence that is front-loaded with the core action. However, the terseness contributes to the missing behavioral context rather than earning its brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained. But for a tool with non-trivial polling, pagination, and filtering semantics, the description says nothing about how or when to poll, leaving the agent to rely solely on the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters (limit, filter, task_id, skip_newest, wait_seconds) are already documented in the schema. The description adds no additional meaning about parameter behavior, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('check status and output') for a 'submitted YADE task', so the agent knows this is a read/retrieval tool. It does not explicitly differentiate itself from siblings like yade_list_tasks, but the 'submitted task' scoping gives reasonable disambiguation.
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?
There is no indication of when to use this versus yade_list_tasks or yade_execute_task, nor any mention of the intended polling pattern (the long-poll behavior in wait_seconds suggests repeated invocation, which is never explained). Usage must be inferred entirely from the name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute Python code synchronously in the running YADE process.
Returns stdout immediately. Code runs in the YADE Python environment where yade modules are already imported; side effects persist.
This tool remains responsive EVEN WHILE a simulation task is running (submitted via yade_execute_task). Use it as a live REPL to inspect simulation state in real time — no need to pre-script print statements.
Typical uses:
Query simulation state: O.bodies count, current iteration
Create/modify bodies, engines, interactions
Read or set material properties
Live inspection during a running simulation (e.g. check stress tensor, coordination number, energy balance, or capture viewport screenshots when GUI is available)
Development and REPL-style testing
O.engines[0] holds a PyRunner that belongs to yade-mcp-bridge (its command mentions "mcp bridge"). Ignore it: assign O.engines as usual, the bridge re-adds the PyRunner before every O.run().
Unlike yade_execute_task, this tool is fire-and-return: the response contains the full output. It is NOT tracked by yade_list_tasks and cannot be interrupted or polled.
Timeout behaviour: on timeout the bridge attempts to abort the
running code. The response is an error envelope (ok=false)
whose error.code is one of:
interrupted — the code was running a simulation cycle
(O.run) and was paused cleanly at an iteration boundary.
For long simulations or solving to equilibrium, switch to
yade_execute_task — it tracks progress and stops cleanly via
yade_interrupt_task.
terminated — a non-cycle abort succeeded (async exception
injection); the pump thread is free, but YADE state may be
partially modified by the code that ran before the abort fired.
Inspect state before retrying.
timeout — abort failed (code stuck in a C extension, or
nested inside a running task's PyRunner tick); the bridge may
still be blocked. Restart if unresponsive.
WARNING: For anything expected to take more than a few seconds,
use yade_execute_task instead — it has proper cancellation via
yade_interrupt_task and does not leave state drift on timeout.
Also, do NOT write except BaseException: in your code; it
defeats bridge-initiated cancellation.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | Python code to execute in YADE process | |
| timeout | No | Seconds before the bridge aborts the snippet; longer work belongs in yade_execute_task. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden and does so thoroughly: fire-and-return semantics, no tracking/polling/interruption, persistent side effects, responsiveness during a running task, and a detailed timeout taxonomy (interrupted / terminated / timeout) with the state-drift consequences of each. It also flags the bridge PyRunner gotcha and the BaseException cancellation pitfall — exactly the behavioral context structured fields cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core behavior and well structured via the 'Typical uses' bullets and the labeled timeout codes, so a reader can stop early. It is nonetheless long, and the warning paragraph partially restates the earlier yade_execute_task/abort guidance rather than adding new information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter code-execution tool with an output schema, everything an agent needs is present: when to use it, when to switch siblings, side-effect persistence, and the failure modes with their remedies. Return values are correctly left to the output schema, and the error-envelope shape is described only where it affects decisions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema for timeout: it explains that on expiry the bridge attempts an abort and that the resulting error envelope's code varies by abort outcome, which effectively explains the parameter's consequences. The code parameter itself is only restated at a high level, keeping this below a 5.
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?
States a specific verb and resource ('Execute Python code synchronously in the running YADE process') plus the key scope trait (runs in the live process with yade modules pre-imported, side effects persist). It explicitly contrasts itself with yade_execute_task, so an agent can distinguish it from the nearest sibling without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides both positive routing ('use as a live REPL to inspect state during a running simulation', with concrete examples) and negative routing ('for anything expected to take more than a few seconds, use yade_execute_task instead', plus the yade_interrupt_task path). The 'Unlike yade_execute_task ... not tracked by yade_list_tasks' sentence closes the alternative-selection question completely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit a Python script for asynchronous execution in YADE.
Returns a task_id immediately; the script is queued and runs in the background. Tasks run one at a time in submit order (they share the YADE process and its single simulation state), so a multi-stage pipeline can be submitted in one go — each stage starts when the previous one finishes. Use the companion tools to manage the task lifecycle:
yade_check_task_status: poll output, progress, and final status
yade_interrupt_task: stop a running task or cancel a queued one
yade_list_tasks: browse task history (also shows queue order)
Use this for production simulation runs, long O.run() cycles, and any operation that may take minutes or longer. For quick queries and REPL-style testing, use yade_execute_code.
O.engines[0] holds a PyRunner that belongs to yade-mcp-bridge (its command mentions "mcp bridge"). The script does not need to keep it: assign O.engines as usual, the bridge re-adds the PyRunner before every O.run().
| Name | Required | Description | Default |
|---|---|---|---|
| description | Yes | Brief task purpose | |
| script_path | Yes | Absolute path to entry Python script for YADE |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so well: it discloses immediate task_id return, background queuing, single-task-at-a-time execution, submit-order pipeline behavior, shared single simulation state, and the special PyRunner bridge behavior before every O.run(). These are exactly the behavioral traits an agent needs before invoking an asynchronous task.
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?
Despite its length, the description is well structured and front-loaded: the core submit-and-return behavior comes first, followed by queue semantics, lifecycle routing, usage distinction, and the bridge detail. Each paragraph or bullet provides actionable information without repetition.
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 inherently complex because it is asynchronous and stateful, and the description covers the critical execution model, ordering guarantees, lifecycle delegation, and usage boundaries. An output schema exists, so return-value details are not required in the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented in the schema. The description adds context about the script being an entry point but does not explain parameter format or semantics beyond what the schema provides, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Submit a Python script for asynchronous execution in YADE') and explicitly distinguishes the tool from yade_execute_code for quick REPL-style use. It also names the lifecycle companion tools, so an agent can place it immediately among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use guidance ('production simulation runs, long O.run() cycles, and any operation that may take minutes or longer') and an explicit alternative for quick work ('use yade_execute_code'). The lifecycle section further routes the agent to status, interrupt, and list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop a running YADE task, or cancel one still waiting in the queue.
A task that has not started yet is simply removed from the queue
and ends in status canceled (method reports
canceled_while_queued). For a running task, two cancellation
paths are applied together by the bridge:
flag_only — sets an interrupt flag that YADE's PyRunner
tick observes between simulation iterations (graceful path
for O.run tasks).
flag_and_async_exc — in addition, injects a TaskInterrupt
exception into the script thread, so pure-Python deadloops
with no O.run on the stack are terminated too.
The response method field reports which path ran. When
async-exc is refused (e.g. target thread is a Dummy-N
boost::python frame), async_exc_skipped_reason explains why.
Namespace after interrupt: the YADE __main__ namespace is
shared between tasks and yade_execute_code calls. Any
variables the interrupted script had already defined —
including O state — are preserved. There's no need to
re-run the whole script to continue work: inspect state with
yade_execute_code or resume via a fresh yade_execute_task
that only runs the remaining logic.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | Task ID returned by yade_execute_task |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description fully discloses behavior: cancellation paths (flag_only, flag_and_async_exc), response method field, namespace preservation, and async exception handling. Very transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with main purpose, but subsequent paragraphs contain detailed technical explanations. While informative, some sentences could be condensed. Still well-structured for the 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?
Covers task states, cancellation paths, namespace impact, and response details. Given the tool's complexity and presence of an output schema, the description is thorough and complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and description adds context: 'Task ID returned by yade_execute_task'. While schema already describes the parameter, the description clarifies its source and usage, adding value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Stop a running YADE task, or cancel one still waiting in the queue.' Specific verb and resource, distinct from sibling tools like yade_execute_task or yade_list_tasks.
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 when to use (interrupt/cancel tasks) and explicitly references alternatives for inspecting state (yade_execute_code) and resuming (yade_execute_task), offering clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tracked YADE tasks with pagination.
Tasks are listed newest first. Queued (pending) tasks run one at a time in submit order, so among the pending entries the one furthest down the list runs next.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max tasks to return | |
| skip_newest | No | Skip N most recent tasks before listing |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses ordering ('newest first') and queue behavior for pending tasks, adding value beyond the schema. However, with no annotations, it could further state that it is read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, each valuable. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, the description sufficiently covers listing, pagination, and ordering. Minor gap: no mention of return fields, but schema compensates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds context about pagination ordering but no new meaning beyond param descriptions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List tracked YADE tasks with pagination' with a specific verb and resource, and implicitly distinguishes from sibling tools like yade_check_task_status by focusing on listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., yade_check_task_status), nor when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search YADE API documentation by keywords (like grep).
Returns matching class/function names with descriptions ranked by relevance. Use yade_browse_api for full documentation of a specific class.
When to use:
You have keywords but don't know the exact class name
Examples: "friction material", "gravity engine", "contact force", "triaxial stress", "sphere create", "hertz mindlin"
Related tools:
yade_browse_api: Get full documentation for a known class path
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results (1-20). | |
| query | Yes | Search keywords for YADE Python API. Examples: 'sphere body', 'triaxial compression', 'contact force'. Case-insensitive. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool returns ranked search results, implying a read-only operation. While it does not explicitly declare no side effects, the nature of a documentation search tool makes this clear. The description could be slightly more explicit about being non-destructive.
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: it opens with the primary action, then describes return values, then provides usage guidance with examples, and finally lists a related tool. Every sentence is informative and relevant.
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 does not need to detail return format. It covers purpose, usage scenarios, concrete query examples, and sibling tool differentiation. It is complete for an agent to decide when to invoke 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?
The input schema has 100% description coverage, so the baseline is 3. The description adds value by providing example queries (e.g., 'sphere body') and the analogy 'like grep', which helps the agent understand how to formulate the query. This enriches the schema's descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches YADE API documentation by keywords, likening it to grep. It specifies that it returns class/function names with descriptions ranked by relevance. This differentiates it from the sibling yade_browse_api, which provides full documentation for a known class.
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 includes a 'When to use' section with concrete examples (e.g., 'friction material', 'gravity engine'). It also tells when to use the alternative tool (yade_browse_api for full documentation of a specific class). This provides clear guidance for the agent to select the correct tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.11.2yade_check_task_status2 fields changedInput schema / properties / wait_seconds / descriptionPrevious value: -"Delay before querying (prevents polling too fast). Use 0 for immediate check."New value: +"Long-poll: return when the task changes state or after this many seconds. 0 = immediate."Input schema / properties / wait_seconds / maximumPrevious value: -3600New value: +20yade_execute_code2 fields changedInput schema / properties / timeout / descriptionPrevious value: -"Console execution timeout in seconds"New value: +"Seconds before the bridge aborts the snippet; longer work belongs in yade_execute_task."Input schema / properties / timeout / maximumPrevious value: -600New value: +20v0.2.3yade_execute_task3 fields changedInput schema / properties / entry_scriptRemoved value: -{
- "description": "Absolute path to entry Python script for YADE",
- "type": "string"
-}Input schema / properties / script_pathAdded value: +{
+ "description": "Absolute path to entry Python script for YADE",
+ "type": "string"
+}Input schema / requiredPrevious value: -[
- "entry_script",
- "description"
-]New value: +[
+ "script_path",
+ "description"
+]yade_browse_api1 field changedInput schema / properties / path / descriptionPrevious value: -"Dot-separated API path to browse. Progressive disclosure:\n- None or '': Root — list all categories\n- 'engines': List all engine classes\n- 'engines.NewtonIntegrator': Full docs for NewtonIntegrator\n- 'materials': List all material classes\n- 'materials.FrictMat': Full docs for FrictMat\n- 'interactions.geometry': List contact geometry classes\n- 'interactions.laws.Law2_ScGeom_FrictPhys_CundallStrack': Full docs\n- 'utils': Utility functions\n- 'omega': Omega (O) simulation control"New value: +"Dot-separated path into YADE's class hierarchy. Navigation is tree-driven (no class-name shortcuts).\n- None or '': list top-level categories (engine / functor / material / shape / ...)\n- 'engine': list direct sub-trees of Engine (Dispatcher, GlobalEngine, PartialEngine, ...)\n- 'engine.GlobalEngine': list GlobalEngine's sub-trees (BoundaryController, Collider, PeriodicEngine, ...) plus its direct leaf classes (NewtonIntegrator, InteractionLoop, ...)\n- 'engine.GlobalEngine.NewtonIntegrator': full docs for NewtonIntegrator\n- 'functor.LawFunctor.Law2_ScGeom_FrictPhys_CundallStrack': full docs for a contact law functor\nEvery leaf is reached via its parent-class chain."yade_check_task_status2 fields changedInput schema / properties / wait_seconds / descriptionPrevious value: -"Wait time before querying status"New value: +"Delay before querying (prevents polling too fast). Use 0 for immediate check."Input schema / properties / wait_seconds / minimumPrevious value: -1New value: +0v0.1.0yade_browse_apiyade_check_task_statusyade_execute_codeyade_execute_taskyade_interrupt_taskyade_list_tasksyade_query_apiScored across 7 tools
The task lifecycle tools, synchronous code execution, and API discovery tools are mostly distinct. The only likely point of confusion is yade_execute_task vs yade_execute_code, but their descriptions clearly separate async tracked production runs from synchronous REPL-style use.
All tools use a consistent yade_ prefix with snake_case verb_noun naming: list_tasks, execute_task, check_task_status, interrupt_task, execute_code, browse_api, query_api. The pattern is predictable throughout.
Seven tools is well-scoped for this server: four task-lifecycle tools, one synchronous execution tool, and two API discovery tools. Each tool has a clear role and the set does not feel bloated or thin.
The core surface is covered: async and sync execution, task listing/status/interrupt, and API browsing/search. Minor lifecycle gaps remain, such as no explicit task deletion/cleanup or separate wait/get-task tool, though yade_check_task_status covers output and final status.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Task management your AI agents can actually run. One line becomes a context-ready task over MCP.
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.