Add a new tool#

This example shows how to add a new @app.tool(...) safely and make it visible at the right stages of an MCP session.

Where to implement#

  1. Add the tool implementation to src/ansys/aedt/mcp/tools.py.

  2. Add the tool to the appropriate group in src/ansys/aedt/mcp/toolsets.py.

  3. Document the tool behavior in Tools and capabilities.

Decorator options and tags#

Use FastMCP’s @app.tool(...) decorator with these key options:

  • tags: Set of tags used for grouping and runtime filtering.

  • timeout: Maximum execution time for the tool.

Use these common tags in this repository:

  • REQUIRES_AEDT_TAG: Mark tools that require an active AEDT connection.

  • aedt_tools: Group core AEDT-facing tools.

  • locked_connection: Mark tools that are disabled when startup uses --connect and locks the connection for the server lifetime.

Use these timeout tiers in this repository:

  • Quick: 30 seconds

  • Medium: 120 seconds

  • Long: 600 seconds

Example: AEDT-dependent tool#

Use REQUIRES_AEDT_TAG when the tool cannot run before connection:

from fastmcp.server import Context
from ansys.aedt.mcp import app
from ansys.aedt.mcp.tools import REQUIRES_AEDT_TAG

@app.tool(tags={"aedt_tools", REQUIRES_AEDT_TAG}, timeout=120)
def my_new_tool(ctx: Context) -> str:
    return "ok"

Example: Pre-connection tool#

Do not use REQUIRES_AEDT_TAG for tools that work before connecting:

from fastmcp.server import Context
from ansys.aedt.mcp import app

@app.tool(tags={"aedt_tools"}, timeout=30)
def check_local_environment(ctx: Context) -> str:
    return "environment ready"

Runtime flags and their effect#

Server startup flags affect tool visibility and behavior:

  • --dynamic-tool-discovery: Hide REQUIRES_AEDT_TAG tools until AEDT connects.

  • --connect: Connect at startup and lock the session. In this mode, launch_aedt, connect_to_aedt, and disconnect_from_aedt are disabled for the life of the process.

  • --include-context: Register optional context tools such as get_guidelines_for.

Validation checklist#

  1. Add or update tests in tests/test_tools.py.

  2. Ensure the tool appears in a toolset definition (validated by tests/test_toolsets.py).

  3. Run tests locally.

  4. Verify that code coverage remains greater than 80%.

  5. Update user-facing documentation.