Create MCP Tools

[DhavalRepo18]

• Start with IoT Agents

[ssiegel95]

• A platform like MCP-Universe will help you test and validate your tools in a scripted and structured way using different agent frameworks
• If you are new to tool writing and the concept of service delivery (tools are presented as services) then it probably would be a good idea to start with Fast MCP as it makes it pretty easy to get started quickly
• Tools should contain in their description as detailed information as possible about the expected calling conventions, return values, etc. This description text makes its way back to the llm via the context window and it can really make the difference between successful tool use and getting caught in a large iteration loop where the agent is trying to figure out how to use your tool. Take, for example, something I was doing. Here's an example of a poorly constructed docstring and a revised one that worked better:

This didn't work well:

1. agents were confused about the format of data_uri (always trying to pass a relative path from the present working directory)
2. no mention of what to expect in return so some agents assumed success even if getting no output back from the tool due to an internal tool error
3. Instructions like "You should confirm your choices of these parameters with the user". are not useful in headless (non-interactive) agentic sessions where there will not necessarily be a user to interact with.

@mcp.tool(
    name="forecast_timeseries",
    description=(
        """
        Forecasts a time series from a URI that points to CSV data.
         You must include `timestamp_column`,`target_columns` and `data_uri`
         in your input payload. The `forecast_length` parameter is optional and defaults to 96.

         Here is an example input payload:

         ```json
         {
             "data_uri": "file://./data.csv",
             "timestamp_column": "timestamp",
             "target_columns": ["value"],
             "identifier_column": "identifier",
             "forecast_length": 96
         }
         ```

         **You should confirm your choices of these parameters with the user.**
         **You should be reluctant to read the full content of the data_uri except to validate its format.**
         """
    ),
)

This worked much better:

1. I'm being much more explicit about how data_uri should be formatted (fully qualified system paths if it's a file)
2. I'm telling the mcp client (and by extension the agent/llm) what to expect in return, where to look for it, and something about its structure

@mcp.tool(
    name="forecast_timeseries",
    description=(
        """
    Generate time series forecasts from tabular data referenced by a URI.

    This tool accepts a `DataInput` object containing a `data_uri` that points to
    a time series dataset (e.g., a CSV file). The tool loads the dataset, performs
    forecasting for each target column, and returns a `ForecastResult` object that
    includes a `forecast_uri` pointing to the generated results file.

    The forecast results are always written to the system's temporary directory.
    Each output file is assigned a unique filename with the prefix `"forecast_result"`,
    and saved in CSV format. The file contains predicted values for each target
    column, beginning immediately after the last timestamp in the input data.

    Args:
        input (DataInput): Input specification containing a URI reference to the source data,
            column mappings, and optional forecasting parameters (e.g., `forecast_length`).
        If the 'data_uri' is a local file, the URI will start with `file://` and it **must** reference
        a fully qualified path (no relative paths are allowed).
        If the 'data_uri' is a remote file, the URI will be a URL.
    Returns:
        ForecastResult: A pydantic model containing the URI to the forecasted results and
        possibly additional contextual data.

    Example Input:

         ```json
         {
             "data_uri": "file:///fully/qualified/path/data.csv",
             "timestamp_column": "timestamp",
             "target_columns": ["value"],
             "identifier_column": "identifier",
             "forecast_length": 96
         }
         ```

         
         """
    ),
)

At some level, the documentation guidelines for tools follows fairly common sensical rules for how you'd want someone to document a normal function that you were asked to use. Try to be explicit about what to expect, what it returns, how it can fail, and restrictions on inputs. This should reduce the number of times an agent needs to iterate to get things correct and reduce the amount of tokens consumed.

On the topic of tokens:

Note that in the case I'm showing here (doing a timeseries forecast on potentially large amounts of data) I'm being very careful about steering the llm away from actually reading all the data. In my task configuration (part of the MCP-universe framework) I give the following prompt:

• tells the llm to not read all the data and pass that through the context (which would quickly consume token budgets). But I do want the llm to perform some basic validation steps on the data to avoid unnecessarily calling a tool (which could itself collect fees for use) with obviously bad inputs.

Your use case might be very different so the above comment about steering the llm away from reading your data in full might not apply, especially if you were doing something like document summarization or translation, for example.

{
    "category": "time_series_forecasting",
    "question": "Perform a forecast on the HUFL column from filesystem_directory/ETTh1.csv. \n
First, read a sample of the file (e.g., first 3 rows) to validate the CSV headers and column \n
structure before proceeding with the full forecast analysis.",

I'm somewhat new to all this myself and will continue to post as I learn more. I ask that you do the same so we can help inform each other. Good luck on your agent/tool journey!

[gganapavarapu]

Adding my observations to @ssiegel95's comments on tool descriptions:

1. If you use low level sdk for FastMCP like mcp.server, the tool decorator can fetch the input and output schema from the function definition. And you can create structured tools with this approach.
2. It becomes easier to bind these structured tools to various models as the input and output schema is clearly present on the tools.
3. Still, semantics of the inputs and outputs are not captured in function signature (and so, in tool signature). Description is a good place to capture the semantics.
4. Depending on positioning of IoT agent, whether it is 1) generic vs 2) special object types or time-series, description should clearly outline the scope. My observation is: except top tier, many models are not good in differentiating tools with overlapping or similar descriptions. Defining scope of the agent/tool in the description would help.