Agents-Core

by IEZhu

Overview Schema Source Related Servers Discussions Admin

Python

Local

Save a personal flow

save_flow

Create or update a personal Markdown flow; use user or repo scope and revision checks to avoid overwriting edits.

Instructions

Create or update a personal flow when the user asks to save or change one.

Stored as Markdown in the installation's git-ignored flows/.user, never in a
repository's working tree. scope: user (all repositories, default) or repo
(only the caller's repository). content: the complete Markdown flow, starting
with a "# Title", with steps and completion criteria; not a chat transcript.
expected_revision: omit to create; to update, pass the revision from get_flow
(a mismatch returns flow_conflict: reload and reapply instead of overwriting).
Built-in flows are read-only: to change one for this user, save the same ID
with override=true. Previous text stays in history.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`flow`	Yes
`scope`	No		user
`content`	Yes
`override`	No
`workspace`	No	Absolute path of your working directory, the project this session works in. Pass it whenever you have one: one server can serve several sessions.
`expected_revision`	No	Optional revision the caller last read; the save is refused if it changed.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv26.10.14+1807Oct 15, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only give the generic write profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description goes well beyond that: exact storage location (git-ignored flows/.user, never a repo working tree), the two scope modes and their defaults, the required Markdown shape of content, the conflict-return contract, and the fact that prior text is retained in history.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in sentence one and every remaining sentence carries operational information (storage, scope, content format, revision, override, history) with no filler. It is dense — some parameters are covered inside a single long sentence — but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter mutation tool with an output schema available, the description covers the write semantics, the concurrency contract, the read-only fallback, and the persistence location. An agent has everything needed to call it correctly without consulting other tools beyond get_flow as directed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 33% (workspace and expected_revision), so the description must compensate and does: it defines scope's semantics and default, what content must contain ('complete Markdown, starting with a # Title... not a chat transcript'), expected_revision's create/update contract, and override's purpose for read-only built-ins. Nearly every parameter that the schema leaves bare is explained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb pair and resource: 'Create or update a personal flow', and immediately scopes it to a triggering condition ('when the user asks to save or change one'). This distinguishes it cleanly from siblings like get_flow, list_flows, and delete_flow without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use ('when the user asks to save or change one'), explicit create-vs-update rule ('omit expected_revision to create'), explicit conflict path (mismatch returns flow_conflict: reload and reapply), and explicit handling of the read-only built-in case via override=true. Alternatives and preconditions are all named.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server