Valuein — SEC EDGAR Fundamentals & Smart-Money Data

Update Report Sections

update_report

Idempotent

Replace one or more sections of an existing report owned by the caller. Useful for authoring workflows where the agent's first draft (create_report) is refined by additional analysis before publishing. Pass citations for figures in the edited prose — they are MERGED into the report's existing set, never replacing it, so omitting them preserves the lineage already recorded. Bumps version. Does NOT change price / tier / visibility — use publish_report for those. Pass drafts_only: true when editing a private draft; a client may then let the edit run without asking. With drafts_only the call is refused (not_a_draft, nothing written) unless the report is private, never published and not signed off. A saved edit returns undo (call undo_change to restore the prior version as a NEW head version; history is kept; refused if the report changed since).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "report_id": "<report_id>",
      "sections": "<sections>"
    },
    "name": "update_report"
  }
}

Input Schema

Name	Required	Description
`title`	No	Optional new title.
`abstract`	No	Optional new abstract.
`sections`	Yes	Sections to replace. Sections not listed are preserved — to DELETE one, name it in `remove_section_ids`. Section ids must match the existing payload.
`citations`	No	Lineage for figures in the edited sections. MERGED into the report's existing citations (first claim wins), never replacing them — so an editor autosave that sends none preserves every citation the report already had.
`report_id`	Yes	Identifier of the report to update, as returned by create_report or list_my_reports.
`drafts_only`	No	Pass true when editing a private draft: the call is refused with `not_a_draft` (nothing written) unless the report is private, never published and not signed off. Lets a client run the edit without asking, because a draft edit is undoable and reaches no reader.
`expected_version`	No	Optimistic concurrency check. If supplied and the current HEAD version is different, the call returns a `version_conflict` error WITHOUT writing. Pass the version you loaded so a concurrent agent edit produces a 'conflict — review' UX instead of silently overwriting (eng review A3A).
`remove_section_ids`	No	Section ids to DELETE outright. Without this, a merge-only update cannot express a deletion: an editor that drops a section simply omits it, the omitted section is preserved, and the caller sees a bumped version with the deleted content still there — a save that reports success and changed nothing. Ids must exist, and the last remaining section cannot be removed (a report with no sections is unreadable); remove the report instead with delete_report.

Output Schema

Name	Required	Description
`undo`	Yes	How to put the record back as it was before this write: call `undo_change` with these args. Null when nothing changed or the change could not be recorded.
`_meta`	Yes	Provenance envelope — data lineage for every MCP response
`report`	Yes
`version`	Yes
`archived`	Yes
`previous_version`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 9, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Adds substantial context beyond the annotations: citations are merged (first claim wins) rather than replaced, version is bumped, drafts_only refuses with `not_a_draft` and writes nothing, and a saved edit returns an `undo` token whose restore is refused if the report changed since. The only gap is that replacing sections and `remove_section_ids` destroy prior prose while destructiveHint=false — this is defensible given full version history and undo, so it is not a contradiction, but the description could state the reversibility guarantee more explicitly.

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?

Front-loaded with the operation, then alternatives, then merge/version behavior, then the drafts_only and undo details — a sensible priority order with no filler sentences. It is dense and long, but nearly every clause carries a distinct behavioral fact an agent needs.

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 an eight-parameter mutation tool with an output schema, the description covers what changes, what is preserved, what is refused and why, and how to revert. Nothing an agent needs in order to call it safely is missing.

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

Parameters4/5

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

Schema coverage is already 100%, so the baseline is 3; the description earns above that by explaining merge semantics for `citations`, the refusal condition behind `drafts_only`, and the conflict-without-writing behavior of `expected_version`. It does not restate section-id matching or the `sections` omission-means-preserve rule, which live in the schema.

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?

Opens with a specific verb and resource ('Replace one or more sections of an existing report owned by the caller') and immediately separates itself from create_report, publish_report and delete_report. An agent can identify the operation and its boundary without opening the 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?

Explicitly names the alternatives and the conditions that select them: price/tier/visibility go to publish_report, deleting a whole report goes to delete_report, restoring a prior version goes to undo_change. It also states when to pass drafts_only: true and when that flag causes refusal.

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

All Valuein — SEC EDGAR Fundamentals & Smart-Money Data tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.