Update a prompt. If the prompt already has runs, this creates a new DRAFT version (current=false) rather than editing in place or publishing — promote it with prompts_publish — so an agent's edits don't go live without a gate. If it has no runs, it is updated in place.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| name | No | ||
| template | No | ||
| llm_model | No | ||
| tag_names | No | ||
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure. It clearly states that updates to prompts with runs do not go live immediately, creating a draft with current=false, and that publishing is a separate step. This is a significant, non-obvious behavior fully disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the primary action, and every clause serves a purpose. It efficiently communicates core functionality and the key versioning nuance without wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential behavior for an update tool: the versioning logic and the distinction between updating in place vs creating a draft. It lacks mention of return values or error conditions, but these are minor for this type of tool, and the core contextual information is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not elaborate on any of the six parameters. While parameter names like 'name' and 'template' are self-explanatory, the description adds no additional meaning or context about how they are used, especially the required 'id' parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Update a prompt,' clearly stating the verb and resource. It also distinguishes the tool from siblings like prompts_publish and prompts_create by explaining the versioning behavior, which is unique and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when the tool creates a draft version (if runs exist) versus editing in place (if no runs). It also tells the user to use prompts_publish to promote a draft, providing clear guidance on workflow and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Each tool targets a distinct resource and action, with clear separation across agreements, datasets, judges, metrics, prompts, runs, tags, and usage. Even similar tools like datasets_create vs datasets_create_from_url and runs_generate vs runs_rerun are explicitly differentiated in their descriptions.
The overwhelming majority of tools follow a consistent plural_resource_action snake_case pattern (e.g., datasets_create, metrics_update, runs_retry_failures). The only slight deviation is promptfoo_import, but it is still descriptive and does not break the overall predictability.
With 54 tools, the server far exceeds the 25+ threshold considered too many, and approaches the 50+ extreme mismatch level. Even for a broad LLM evaluation platform, this count is excessive and likely to overwhelm agents, making tool selection more error-prone.
The toolset provides full CRUD for core resources (datasets, metrics, prompts, runs, tags) plus lifecycle operations like publish, generate, regrade, and retry. It also includes cross-cutting utilities (usage, import, provider credentials). Minor gaps exist, such as no update/delete for agreements and no cross-run response search, but these are non-essential for the primary workflows.
