Optimize a prompt from a session

The best signal for improving a prompt is watching it fall short in a real session — it missed a constraint, returned the wrong format, or left out a field you needed. Because the same agent that used the prompt can also edit it, you can turn that moment into a lasting fix instead of repeating the correction every time.

This is apistash's core loop in miniature: use the AI to improve the tools the AI relies on.

This workflow edits customer prompts in a writable ownership space. Platform prompts are maintained by apistash and cannot be updated with these tools.

The loop

1. Spot the shortfall. In the session, you notice the prompt produced something it shouldn't have — say a summarize-ticket prompt that keeps dropping the ticket's severity.
2. Have the agent read the current prompt. get_prompt returns the raw template, with its {{placeholders}} intact — the exact text to revise.
3. Ask it to revise, grounded in what just happened. Tell the agent what went wrong, in the terms you just saw it fail. It rewrites the template to fix that specific gap — adding the missing instruction, tightening the output format, or declaring a new argument.
4. Save it. update_prompt stores the revised template. A changed template is appended as a new version — the previous one is never lost, so you can restore it if the change overshoots.
5. Re-run to confirm. Run the same task again against the new version and check the shortfall is gone.

Example

Your agent just summarised a ticket and left out the severity. Instead of correcting the output by hand, correct the prompt:

You dropped the severity again. Read the summarize-ticket prompt with get_prompt, then update it so the summary always includes a labelled Severity: line taken from the ticket. Save it with update_prompt.

The agent reads the stored template:

Summarize the following support ticket for an on-call engineer: {{ticket}}

…and saves a revised version:

Summarize the following support ticket for an on-call engineer. Begin with a line Severity: <level> taken from the ticket, then a one-paragraph summary: {{ticket}}

The next call to summarize-ticket starts from the improved template — the fix is durable, not a per-session reminder.

Why versioning makes this safe

Every edit is a new version, and the latest is the one served. That means you can iterate freely: revise, test, and if a change makes things worse, roll back to the previous version. You're never one bad edit away from losing a prompt that worked. See Prompts → Versioning.

Keep content and arguments in step

If the fix needs a new input — say the prompt should take a separate {{product}} — declare the argument and reference it in the content in the same update_prompt call. A template that mentions a {{name}} it doesn't declare, or declares one it never uses, is rejected. See Prompts → Arguments.

The same loop for resources and tools

The pattern isn't limited to prompts:

• Resources — when a reference document your agent reads is out of date, have it refresh the resource with update_resource or patch_resource. See Maintain a living document with your agent.
• Custom tools — when a connector call fails, have the agent fix the definition with update_custom_tool. See Turn an API into a tool.

info

A standalone personal credential edits its prompts by bare name. In organization scope, the agent uses me/name for the represented member's private prompt or <team>/name for a bound team. A bare name reads the organization's shared catalogue; catalogue revisions stay in the dashboard, while the agent can copy the prompt into a writable private or team space.