Design: Tool payload formats

[evaline-ju]

The current tool payload format nests tool request arguments as tool_args

payload_args = {
        "tool_name": body["params"]["name"],
        "tool_args": body["params"]["arguments"],
        "client_session_id": "replaceme",
    }
    payload = ToolPreInvokePayload(name=body["params"]["name"], args=payload_args)

Ref: https://github.com/kagenti/plugins-adapter/blob/88a37f70f19bd78dfb0da4b6a04803377030f38f/src/server.py#L58C5-L63C83

One issue present is this requires plugins to process potentially nested arguments e.g.

payload_args={
  "tool_name": "test2_hello_world",
  "tool_args": {
    "name": "bob"
  },
  "client_session_id": "replaceme"
}

Alternate options:
(1) Tool arguments can be flattened like payload_args = { **body["params"]["arguments"] ...} but this could risk collisions such as if "tool_name": "bob" were provided

(2) Other fields moved to another nested field (e.g. metadata) to remove some of the collision risk but still presents one level of nesting that plugins have to process. Naming for arguments vs. tool_args depending on how specific payloads are to MCP primitives can be subject to discussion

payload_args = {
    "arguments": body["params"]["arguments"], 
    "metadata": {
        "tool_name": body["params"]["name"],
        "client_session_id": "replaceme",
    }
}

(3) Potential combination of the above

payload_args = {
    **body["params"]["arguments"],
    "metadata": {
        "tool_name": body["params"]["name"],
        "client_session_id": "replaceme",
    }
}

In all cases, any alterations to fields will require the ext-proc logic to parse the fields into the expected format to continue the flow (e.g. expected request format or response format)

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in 14 days if no further activity occurs. If this issue is still relevant, please comment or remove the stale label.

[evaline-ju]

moving toward a more common payload format is still relevant, just not immediately prioritized