Schema Modifiers

Learn how to use schema modifiers to transform tool schemas before they are seen by agents.

Schema modifiers are part of Composio SDK’s powerful middleware capabilities that allow you to customize and extend the behavior of tools.

Schema Modifiers

Schema modifiers transform a tool’s schema before the tool is seen by an agent.

Schema Modifier

Useful for:

  • Modifying or rewriting the tool description to better fit your use case.
  • Adding arguments to the tool. For example, adding a thought argument to the tool to prompt the agent to explain the reasoning.
  • Hiding arguments from the tool. In cases where the argument is irrelevant to the tool.
  • Adding extra arguments to the tool schema for custom use cases or execution.
  • Adding default values to tool arguments.

Below we modify the schema of the HACKERNEWS_GET_LATEST_POSTS to make the size argument required and remove the page argument.

1from composio import Composio, schema_modifier
2from composio.types import Tool
3
4user_id = "your@email.com"
5
6@schema_modifier(tools=["HACKERNEWS_GET_LATEST_POSTS"])
7def modify_schema(
8 tool: str,
9 toolkit: str,
10 schema: Tool,
11) -> Tool:
12 _ = schema.input_parameters["properties"].pop("page", None)
13 schema.input_parameters["required"] = ["size"]
14 return schema
15
16tools = composio.tools.get(
17 user_id=user_id,
18 tools=["HACKERNEWS_GET_LATEST_POSTS", "HACKERNEWS_GET_USER"],
19 modifiers=[
20 modify_schema,
21 ]
22)

In using the above modified tool schema, the page argument is removed and the size argument is required.

You can test this out by viewing the tool call response in the LLM too!

1from openai import OpenAI
2from composio import Composio, schema_modifier
3from composio.types import Tool
4from composio_openai import OpenAIProvider
5
6
7@schema_modifier(tools=["HACKERNEWS_GET_LATEST_POSTS"])
8def modify_schema(
9 tool: str,
10 toolkit: str,
11 schema: Tool,
12) -> Tool:
13 _ = schema.input_parameters["properties"].pop("page", None)
14 schema.input_parameters["required"] = ["size"]
15 return schema
16
17# Initialize tools.
18openai_client = OpenAI()
19composio = Composio(provider=OpenAIProvider())
20
21# Define task.
22task = "Get the latest posts from Hacker News"
23
24# Get GitHub tools that are pre-configured
25tools = composio.tools.get(
26 user_id="default",
27 tools=['HACKERNEWS_GET_LATEST_POSTS', 'HACKERNEWS_GET_USER'],
28 modifiers=[
29 modify_schema,
30 ],
31)
32
33# Get response from the LLM
34response = openai_client.chat.completions.create(
35 model="gpt-4o-mini",
36 tools=tools,
37 messages=[
38 {"role": "system", "content": "You are a helpful assistant."},
39 {"role": "user", "content": task},
40 ],
41)
42print(response)
43
44# Execute the function calls.
45result = composio.provider.handle_tool_calls(response=response, user_id="default")
46print(result)

Example: Modifying the tool description

Sometimes you need to provide additional context to help the agent understand how to use a tool correctly. This example demonstrates modifying the description of the GITHUB_LIST_REPOSITORY_ISSUES tool to specify a default repository when none is provided.

This approach is particularly useful when you want to guide the agent’s behavior without changing the tool’s underlying functionality.

In this example:

  • We append additional instructions to the tool’s description
  • The modified description tells the agent to use composiohq/composio as the default repository
  • This helps prevent errors when the agent forgets to specify a repository parameter
1from composio import Composio, schema_modifier
2from composio.types import Tool
3from composio_google import GoogleProvider
4from google import genai
5from google.genai import types
6from uuid import uuid4
7
8composio = Composio(provider=GoogleProvider())
9client = genai.Client()
10user_id = uuid4() # User ID from DB/App
11
12
13@schema_modifier(tools=["GITHUB_LIST_REPOSITORY_ISSUES"])
14def append_repository(
15 tool: str,
16 toolkit: str,
17 schema: Tool,
18) -> Tool:
19 schema.description += " When not specified, use the `composiohq/composio` repository"
20 return schema
21
22
23tools = composio.tools.get(
24 user_id=user_id, tools=["GITHUB_LIST_REPOSITORY_ISSUES"], modifiers=[append_repository]
25)
26
27print(tools)