[Feature] Support for more tool kinds

[MaryamZi]

Description
Currently, only MCP tools are supported. Also see #8.

Use Case
It's fairly common for agents to use functions as tools. It will be nice to supports the same with AFM.

Similarly, we could also support deriving tools from OpenAPI specifications for existing services.

Proposed Solution
Support for functions as tools and/or tools derived from OpenAPI specifications.

Note: for functions as tools, we also need to consider

• minimizing impact on portability
• not all implementations may be able to support it (e.g., may require dynamic loading)

[RukshanRanasinghe2000]

@MaryamZi

Proposal: Support for More Tool Kinds in AFM

As I understand, currently AFM supports only MCP tools, but many agents also need simpler or more flexible tools such as functions or OpenAPI-based tools.

---

Background

AFM currently allows only MCP tools. Many real-world agent use cases require:

• Function tools — simple local functions
• OpenAPI tools — calling existing APIs via OpenAPI specifications

Supporting these tool types will make AFM more flexible while keeping it portable.

---

Proposed Solution

Introduce a type field in tool definitions to allow specifying additional tool kinds.

Example: Function Tool

tools:
  - name: addNumbers
    type: function
    description: Adds two numbers
    parameters:
      a:
        type: number
      b:
        type: number

Example: OpenAPI Tool

tools:
  - name: userService
    type: openapi
    spec: "https://api.example.com/openapi.json"

Implementation Guidance

• Support for function or openapi tools is optional.
• Implementations that cannot support a tool type should ignore it or return a clear error.

[MaryamZi]

@RukshanRanasinghe2000, appreciate the input!

Regarding functions as tools, given that it could impact portability (both across frameworks and AFM implementations - e.g., interpreters vs code generators), we're not sure if we should be rushing into support it (especially given that MCP over STDIO could be a good-enough alternative for now). WDYT?

For OpenAPI spec-based tools, while there is a standard, there is a fair amount of complexity involved. Although these are generally implementation-specific, they could impact AFM definitions. Sharing below a version of a proposal/analysis we worked on some time ago too.

Given that there are already OpenAPI to MCP bridges available, I wonder if we should hold off on this too.

OpenAPI spec-based tools

The OpenAPI spec already defines tool name, description, input/output schema, and authentication, which could map to definitions like

  tools:
    openapi:
      - name: string                  # connection identifier
        spec: string                  # URL or path to OpenAPI spec
        server: string                # optional, override spec's servers
        authentication: object        # optional, existing AFM auth schema
        operations:
          allow: [string | object]    # optional whitelist
          deny: [string | object]     # optional blacklist

But there are some complexities.

Parameter mapping

[Implementations] OpenAPI operations could include path parameters, query parameters, header parameters, and request bodies. These need to be mapped to a single tool input schema for the LLM. This may require the different parameter and input kinds being flattened to a single input schema, but may also need to take into account potential conflicts.$ref references in the spec would need to be resolved when building the tool schema. oneOf/anyOf constructs may need to be simplified or flattened too.

[Spec] Implementations will also have to separate out user/implementation-provided headers (e.g., auth-related). Similarly, there could be parameters, request body fields, etc. the user needs to specify (vs the LLM), and from a spec-point of view, there may need to be a way to specify these.

Response handling

While returning the response directly may generally work, also need to consider aspects like pagination and if responses need to be truncated before sending back to the LLM, and in turn, if the spec needs to say something about it.

Tool identifiers (that also become tool names)

While some operations have an operationId, since it is not mandatory it may not be sufficient to be required as the only identifier for an operation. Therefore, we may have to support both operationId or path and method.

By operationId (string):

  - "gmail.users.drafts.list"

By path and method (object):

  - path: "/users/{userId}/drafts"
    method: "get"
    name: "getDrafts"    # optional, can be derived otherwise

Authentication

Although less common, OpenAPI specifications could specify methods (schemes) by operation instead of or in addition to a global configuration.

openapi: "3.0.0"
info:
  title: Store Management API
  version: "1.0.0"

components:
  securitySchemes:
    PublicApiKey:
      type: apiKey      
      in: header
      name: X-API-Key
    AdminToken:
      type: http
      scheme: bearer

paths:
  /products:
    get:
      operationId: listProducts
      security:
        - PublicApiKey: []
      responses:
        '200':
          description: OK

  /admin/inventory:
    post:
      operationId: updateInventory
      security:
        - AdminToken: []
      responses:
        '200':
          description: OK

We could make this work with our authentication configuration, allowing the authentication field to either be the authentication object or a map of authentication objects.

tools:
  openapi:
    - name: "store_api"
      spec: "https://example.com/store-api.yaml"
      authentication:
        PublicApiKey:
          type: "api_key"
          key: "${env:STORE_API_KEY}"
        AdminToken:
          type: "bearer"
          token: "${env:ADMIN_TOKEN}"
      operations:
        allow:
          - "listProducts"
          - "updateInventory"

Other

• Tool description - Can recommend prioritizing using summary or description or operationId or path + method as tool description in order depending on what is available.
• Implementations may have to support Swagger 2.0 and OpenAPI 3.x, but the spec won’t mention anything about the version (what’s in the spec doesn’t directly map to anything that changed between the two).

---

MCP bridges for these OpenAPI specs designed specifically for use via LLMs, would often have considered these and abstracted out complexities already.

[RukshanRanasinghe2000]

Thanks for the detailed analysis @MaryamZi i. The OpenAPI proposal is thorough and the tradeoffs are real.

A few thoughts:

On function tools — I agree with the hesitation. The portability concern is significant. If an AFM file references a local function, it becomes tied to a specific runtime or codebase, which undermines the "portable agent definition" goal. MCP over STDIO is a reasonable escape hatch for now. Maybe we revisit this once there's a clearer story around how implementations handle dynamic loading.

On OpenAPI tools — the complexity you've outlined (parameter flattening, $ref resolution, per-operation auth, pagination) is real, but most of it is implementation burden, not spec burden. The spec could stay relatively thin and just define the shape of the openapi tool block, leaving the hard parts to implementors.

The operations.allow/deny pattern with both operationId and path+method support is a solid approach. One thing worth considering: should the spec mandate that unrecognized or unsupported tool types are silently ignored vs. surfacing an error? That decision has a big impact on portability.

Even though OpenAPI-to-MCP bridges exist, I’d still lean toward specifying OpenAPI support now (as optional/experimental), and letting implementations decide how deeply to support it. This allows AFM definitions to express intent without blocking on full implementation support.

Happy to help draft this further if needed.

[RukshanRanasinghe2000]

@MaryamZi

This idea may not directly address the issue, but after going through the repo and related docs, I noticed that currently it mainly shows examples.

I think it would be really helpful to have a templating or builder system so users can easily try out Agent-Flavored Markdown without writing everything manually.

To explore this idea, I built a small experiment:

https://github.com/RukshanRanasinghe2000/AgentFactory

If you are interested in this direction, please refer to this repo.

It provides a way to generate AFM-style agent specs through a guided UI and AI-assisted flow, making it easier to create and test agents.