> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Schema Modifiers

> Customize how tools appear to agents

> [!NOTE]
>
> If you're building an agent, we recommend using [sessions](https://composio-preview.mintlify.site/docs/configuring-sessions.md) instead. See [Tools and toolkits](https://composio-preview.mintlify.site/docs/how-composio-works.md#meta-tools) for how sessions handle tool discovery and execution automatically.

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

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

![Schema Modifier](https://mintcdn.com/composio-preview/8QmhU-UXaqTdWL9_/images/schema-modifier.png?fit=max\&auto=format\&n=8QmhU-UXaqTdWL9_\&q=85\&s=f8181a41caea77de5fc6425f5066f7f4)

**Useful for:**

* Modifying or rewriting the tool description to better fit your use case
* Adding arguments to the tool (e.g., adding a `thought` argument to prompt the agent to explain reasoning)
* Hiding arguments from the tool when they're irrelevant
* Adding extra arguments for custom use cases
* Adding default values to tool arguments

> [!NOTE]
>
> Below we modify the schema of `HACKERNEWS_GET_LATEST_POSTS` to make the `size` argument required and remove the `page` argument.

> [tab] Python
>
> ```python theme={null}
> from composio import Composio, schema_modifier
> from composio.types import Tool
>
> composio = Composio()
> user_id = "your@email.com"
>
> @schema_modifier(tools=["HACKERNEWS_GET_LATEST_POSTS"])
> def modify_schema(
>     tool: str,
>     toolkit: str,
>     schema: Tool,
> ) -> Tool:
>     _ = schema.input_parameters["properties"].pop("page", None)
>     schema.input_parameters["required"] = ["size"]
>     return schema
>
> tools = composio.tools.get(
>     user_id=user_id,
>     tools=["HACKERNEWS_GET_LATEST_POSTS", "HACKERNEWS_GET_USER"],
>     modifiers=[
>         modify_schema,
>     ]
> )
>
> print(tools)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> const userId = "your@email.com";
>
> const tools = await composio.tools.get(
>   userId,
>   {
>     tools: ["HACKERNEWS_GET_LATEST_POSTS", "HACKERNEWS_GET_USER"],
>   },
>   {
>     modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
>       if (toolSlug === "HACKERNEWS_GET_LATEST_POSTS") {
>         const { inputParameters } = schema;
>         if (inputParameters?.properties) {
>           delete inputParameters.properties["page"];
>         }
>         inputParameters.required = ["size"];
>       }
>       return schema;
>     },
>   }
> );
>
> console.log(JSON.stringify(tools, null, 2));
> ```

With the modified tool schema, the `page` argument is removed and `size` is required.

> [accordion] Full example with LLM
>
> > [tab] Python
> >
> > ```python theme={null}
> > from openai import OpenAI
> > from composio import Composio, schema_modifier
> > from composio.types import Tool
> > from composio_openai import OpenAIProvider
> >
> > @schema_modifier(tools=["HACKERNEWS_GET_LATEST_POSTS"])
> > def modify_schema(
> >     tool: str,
> >     toolkit: str,
> >     schema: Tool,
> > ) -> Tool:
> >     _ = schema.input_parameters["properties"].pop("page", None)
> >     schema.input_parameters["required"] = ["size"]
> >     return schema
> >
> > # Initialize tools
> > openai_client = OpenAI()
> > provider = OpenAIProvider()
> > composio = Composio(provider=provider)
> >
> > # Define task
> > task = "Get the latest posts from Hacker News"
> >
> > # Get tools with modifier
> > tools = composio.tools.get(
> >   user_id="default",
> >   tools=['HACKERNEWS_GET_LATEST_POSTS', 'HACKERNEWS_GET_USER'],
> >   modifiers=[
> >       modify_schema,
> >   ],
> > )
> >
> > # Get response from the LLM
> > response = openai_client.chat.completions.create(
> >     model="gpt-5.4",
> >     tools=tools,
> >     messages=[
> >         {"role": "system", "content": "You are a helpful assistant."},
> >         {"role": "user", "content": task},
> >     ],
> > )
> > print(response)
> >
> > # Execute the function calls
> > result = provider.handle_tool_calls(response=response, user_id="default")
> > print(result)
> > ```
>
> > [tab] TypeScript
> >
> > ```typescript theme={null}
> > import { Composio } from '@composio/core';
> > import { OpenAI } from 'openai';
> >
> > // Initialize tools (OpenAIProvider is the default provider)
> > const openai = new OpenAI();
> > const composio = new Composio();
> >
> > // Define task
> > const task = 'Get the latest posts from Hacker News';
> >
> > // Get tools with modifier
> > const tools = await composio.tools.get(
> >   'default',
> >   {
> >     tools: ['HACKERNEWS_GET_LATEST_POSTS', 'HACKERNEWS_GET_USER'],
> >   },
> >   {
> >     modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
> >       if (toolSlug === 'HACKERNEWS_GET_LATEST_POSTS') {
> >         const { inputParameters } = schema;
> >         if (inputParameters?.properties) {
> >           delete inputParameters.properties['page'];
> >         }
> >         inputParameters.required = ['size'];
> >       }
> >       return schema;
> >     },
> >   }
> > );
> >
> > // Get response from the LLM
> > const response = await openai.chat.completions.create({
> >   model: 'gpt-5.4',
> >   tools: tools,
> >   messages: [
> >     { role: 'system', content: 'You are a helpful assistant.' },
> >     { role: 'user', content: task },
> >   ],
> > });
> > console.log(response);
> >
> > // Execute the function calls
> > const result = await composio.provider.handleToolCalls('default', response);
> > console.log(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 `GITHUB_LIST_REPOSITORY_ISSUES` to specify a default repository.

> [!NOTE]
>
> This approach is 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

> [tab] Python
>
> ```python theme={null}
> from composio import Composio, schema_modifier
> from composio.types import Tool
> from uuid import uuid4
>
> composio = Composio()
> user_id = str(uuid4())
>
> @schema_modifier(tools=["GITHUB_LIST_REPOSITORY_ISSUES"])
> def append_repository(
>     tool: str,
>     toolkit: str,
>     schema: Tool,
> ) -> Tool:
>     schema.description += " When not specified, use the `composiohq/composio` repository"
>     return schema
>
> tools = composio.tools.get(
>     user_id=user_id,
>     tools=["GITHUB_LIST_REPOSITORY_ISSUES"],
>     modifiers=[append_repository]
> )
>
> print(tools)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> import { v4 as uuidv4 } from 'uuid';
>
> const userId = uuidv4();
> const composio = new Composio();
>
> const addDescription = ({ toolSlug, toolkitSlug, schema }) => {
>   if (toolSlug === 'GITHUB_LIST_REPOSITORY_ISSUES') {
>     schema.description += ' When not specified, use the `composiohq/composio` repository';
>   }
>   return schema;
> };
>
> const tools = await composio.tools.get(
>   userId,
>   {
>     tools: ['GITHUB_LIST_REPOSITORY_ISSUES'],
>   },
>   {
>     modifySchema: addDescription,
>   }
> );
>
> console.log(tools);
> ```

## Next

> [card] [Before execution modifiers](https://composio-preview.mintlify.site/docs/tools-direct/modify-tool-behavior/before-execution-modifiers.md)
>
> Modify tool arguments before execution
