Tool variations
Endpoints listed in an OpenAPI document may lack clear summaries and descriptions that convey their intent and use. When a tool definition inherits an incomplete or vague description, LLMs may struggle to understand when to invoke the tool, how to use it properly, or how to interpret its output.
Improving tool descriptions is a form of prompt engineering, and it’s a critical step in building reliable, effective agents.
Gram provides two ways to improve a tool’s description:
- Editing the OpenAPI document and adding the
x-gramextension to the endpoint to override or enrich the tool’s metadata. - Using the Gram Playground to directly edit a tool’s name and description. This feature is called Tool variations.
Under the Tools tab for a toolset, you can edit the name and description of a tool.
To edit a tool’s name, click the 3 dots and select Edit name. Update the tool name in the modal that opens.
Similarly, to edit a tool’s description, click the 3 dots and select Edit description. Use the dedicated modal to validate and save your updated description:
The Tools tab also lets you add or override a tool’s tags, just like editing its name or description. Tags assigned here participate in tag-based tool filtering, which lets MCP clients connect to a focused subset of a server’s tools.
To edit a tool’s tags, click the 3 dots and update the tags in the modal that opens.
Tag variations take precedence over a tool’s source tags (from OpenAPI operations or Gram Functions). Setting tags through a variation replaces the source tags, and clearing them to an empty set removes the tool from every tag filter. For the full precedence rules, see tag-based tool filtering.