Skip to main content
Glama

Valuein — SEC EDGAR Fundamentals & Smart-Money Data

Generate Research Brief (docx)

generate_research_brief_docx

Render a structured research brief into a professionally-styled Word document — a branded masthead-first page (Valuein letterhead: brand rule, wordmark, 'EQUITY RESEARCH' kicker + date, then the ticker eyebrow, the title as hero, and the named analyst's byline), the body (abstract, optional snapshot table with figures in mono, markdown sections incl. GFM tables, and a citations table with clickable SEC EDGAR links), with a running footer (ticker, 'Built on Valuein · valuein.biz', page number, a single disclosure line) repeated on every page. No embedded charts in v1; pair with generate_dcf_xlsx / generate_comps_xlsx for visuals the analyst pastes in.

SERVER-TRUST: prose, snapshot rows, and citations are rendered as-supplied and are NOT verified by Valuein, so the brief carries a visible 'figures supplied by caller, not verified by Valuein' watermark (response verification.status = 'unverified'). Resolve each citation via verify_fact_lineage before publishing.

Consumes the same sections + citations shape create_report emits, so the typical flow is two tool calls: create_report → generate_research_brief_docx.

Tier: pro+.

Input Schema

NameRequiredDescriptionDefault
titleYesDocument title rendered in the page-1 masthead (1–200 chars).
tickerYesStock ticker symbol the brief covers, e.g. AAPL, MSFT, BRK.B.
abstractNoOptional executive-summary paragraph (≤2000 chars) shown after the masthead.
sectionsYesOrdered body sections of the brief (1–20); each has a heading and body text.
snapshotNoOptional at-a-glance metric rows (≤20) rendered as the snapshot table.
citationsNoOptional source citations (≤60) rendered as a table with clickable SEC EDGAR hyperlinks.
author_nameNoDisplay name of the analyst producing this brief, shown as a named byline ('By {name}') on the masthead — the way a real research note credits an analyst. Omit to show just the date.
company_nameNoOptional display name shown in the masthead subtitle; falls back to the ticker if omitted.

Output Schema

NameRequiredDescriptionDefault
urlYes
_metaYesProvenance envelope — data lineage for every MCP response
r2_keyYes
filenameYes
expires_atYes
size_bytesYes
content_typeYes
verificationYesServer-trust record. Brief prose, snapshot rows, and citations are rendered as supplied and are NOT verified by Valuein, so the brief carries a visible 'figures supplied by caller' watermark. Resolve each citation via verify_fact_lineage for one-click SEC verification.
expires_in_secondsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / properties / _meta / properties / cost_usd / properties / basis / description
      Previous value: -"payg_charge = real charge (agent-pay or your balance). payg_rate_card = indicative price, not billed."New value: +"payg_charge = real pay-per-call charge (a card or MPP payment through agent-pay). payg_rate_card = indicative price, not billed."
  2. Changed2 schema fields changed
    • changedOutput schema / properties / _meta / properties / cost_usd / properties / basis / description
      Previous value: -"payg_charge = real agent-pay charge. payg_rate_card = indicative price, not billed."New value: +"payg_charge = real charge (agent-pay or your balance). payg_rate_card = indicative price, not billed."
    • changedOutput schema / properties / _meta / properties / cost_usd / properties / billed / description
      Previous value: -"true = this amount was actually charged via PAYG for this call. false = indicative PAYG-equivalent value; your plan already covers this call for free."New value: +"true = this amount was actually charged via PAYG for this call. false = indicative PAYG-equivalent value only: no charge was made for this call (it was within your plan)."
  3. Added
  4. Removed
  5. Changed1 schema field changed
    • changedOutput schema / properties / _meta / properties / fundamentals_as_of / description
      Previous value: -"ISO timestamp when the FINANCIAL STATEMENTS were last rebuilt. Use THIS — not `last_updated` — when telling a user how current the fundamentals are. The snapshot is republished on every weekday price refresh while the statements are carried forward unchanged, so `last_updated` can be far more recent than the numbers it sits next to."New value: +"ISO timestamp when the FINANCIAL STATEMENTS were last rebuilt in bulk. Use THIS — not `last_updated` — when telling a user how current the cross-sectional fundamentals are. The snapshot is republished on every weekday price refresh while the statements are carried forward unchanged, so `last_updated` can be far more recent than the numbers it sits next to. It is a floor for a single filer, not a ceiling: a filer with a live partition receives its filing, facts and ratios intraday (minutes after EDGAR dissemination), so an entity-scoped read may carry a filing newer than this; cross-sectional ranks (factor scores, earnings signals) refresh with the weekly bulk export."
  6. Changed2 schema fields changed
    • addedOutput schema / properties / _meta / properties / fundamentals_as_of
      Added value: +{
      +  "description": "ISO timestamp when the FINANCIAL STATEMENTS were last rebuilt. Use THIS — not `last_updated` — when telling a user how current the fundamentals are. The snapshot is republished on every weekday price refresh while the statements are carried forward unchanged, so `last_updated` can be far more recent than the numbers it sits next to.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / _meta / properties / price_as_of
      Added value: +{
      +  "description": "ISO timestamp when the price surfaces were last refreshed.",
      +  "type": "string"
      +}
  7. Changed6 schema fields changed
    • changedInput schema / properties / abstract / description
      Previous value: -"Optional executive-summary paragraph (≤2000 chars) shown after the cover page."New value: +"Optional executive-summary paragraph (≤2000 chars) shown after the masthead."
    • addedInput schema / properties / author_name
      Added value: +{
      +  "description": "Display name of the analyst producing this brief, shown as a named byline ('By {name}') on the masthead — the way a real research note credits an analyst. Omit to show just the date.",
      +  "maxLength": 120,
      +  "type": "string"
      +}
    • changedInput schema / properties / company_name / description
      Previous value: -"Optional display name shown on the cover page; falls back to the ticker if omitted."New value: +"Optional display name shown in the masthead subtitle; falls back to the ticker if omitted."
    • changedInput schema / properties / title / description
      Previous value: -"Document title rendered on the cover page (1–200 chars)."New value: +"Document title rendered in the page-1 masthead (1–200 chars)."
    • addedOutput schema / properties / _meta / properties / cost_usd
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Per-call cost transparency. Omitted for subscription-only tools that have no PAYG-equivalent price.",
      +  "properties": {
      +    "amount_usd": {
      +      "minimum": 0,
      +      "type": "number"
      +    },
      +    "basis": {
      +      "description": "payg_charge = real agent-pay charge. payg_rate_card = indicative price, not billed.",
      +      "enum": [
      +        "payg_charge",
      +        "payg_rate_card"
      +      ],
      +      "type": "string"
      +    },
      +    "billed": {
      +      "description": "true = this amount was actually charged via PAYG for this call. false = indicative PAYG-equivalent value; your plan already covers this call for free.",
      +      "type": "boolean"
      +    }
      +  },
      +  "required": [
      +    "amount_usd",
      +    "billed",
      +    "basis"
      +  ],
      +  "type": "object"
      +}
    • addedOutput schema / properties / _meta / properties / latency_ms
      Added value: +{
      +  "description": "Wall-clock milliseconds this tool call took, measured server-side around the handler.",
      +  "minimum": 0,
      +  "type": "integer"
      +}
  8. Changed2 schema fields changed
    • addedOutput schema / properties / verification
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Server-trust record. Brief prose, snapshot rows, and citations are rendered as supplied and are NOT verified by Valuein, so the brief carries a visible 'figures supplied by caller' watermark. Resolve each citation via verify_fact_lineage for one-click SEC verification.",
      +  "properties": {
      +    "note": {
      +      "type": "string"
      +    },
      +    "status": {
      +      "const": "unverified",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "status",
      +    "note"
      +  ],
      +  "type": "object"
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "_meta",
      -  "url",
      -  "r2_key",
      -  "filename",
      -  "content_type",
      -  "size_bytes",
      -  "expires_in_seconds",
      -  "expires_at"
      -]New value: +[
      +  "_meta",
      +  "url",
      +  "r2_key",
      +  "filename",
      +  "content_type",
      +  "size_bytes",
      +  "expires_in_seconds",
      +  "expires_at",
      +  "verification"
      +]
  9. Changed1 schema field changed
    • addedOutput schema / properties / _meta / properties / pit_safe / description
      Added value: +"true iff a zero-look-ahead point-in-time cut was applied to every returned figure"
  10. Changed7 schema fields changed
    • addedInput schema / properties / abstract / description
      Added value: +"Optional executive-summary paragraph (≤2000 chars) shown after the cover page."
    • addedInput schema / properties / citations / description
      Added value: +"Optional source citations (≤60) rendered as a table with clickable SEC EDGAR hyperlinks."
    • addedInput schema / properties / company_name / description
      Added value: +"Optional display name shown on the cover page; falls back to the ticker if omitted."
    • addedInput schema / properties / sections / description
      Added value: +"Ordered body sections of the brief (1–20); each has a heading and body text."
    • addedInput schema / properties / snapshot / description
      Added value: +"Optional at-a-glance metric rows (≤20) rendered as the snapshot table."
    • addedInput schema / properties / ticker / description
      Added value: +"Stock ticker symbol the brief covers, e.g. AAPL, MSFT, BRK.B."
    • addedInput schema / properties / title / description
      Added value: +"Document title rendered on the cover page (1–200 chars)."
  11. Added

TDQS

A4.6/5.0
Behavior4/5

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

Annotations only tell the agent this is a non-read-only, non-destructive, non-idempotent, closed-world call. The description adds real behavioral context beyond that: content is rendered as-supplied and unverified, a visible 'figures supplied by caller, not verified by Valuein' watermark is stamped on the document, response `verification.status` is 'unverified', and the tool requires pro+ tier. It stops short of saying whether calls persist an artifact or what happens on repeat invocations.

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 core action in the first clause and organized into purpose / trust / flow / tier paragraphs, which suits a document-rendering tool. The masthead enumeration ('brand rule, wordmark, EQUITY RESEARCH kicker + date…') is decorative detail that does not help an agent decide or invoke, and is the main thing keeping this from a 5.

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?

With an output schema present and 100% schema coverage, the description only needs to supply routing and trust context — and it does: the upstream/downstream call flow, the verification/watermark caveat, chart scope limits, and tier gating. Nothing an agent needs to call this correctly 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 description coverage is 100%, so the baseline is 3, but the description adds rendering semantics the schema lacks: `title` becomes the hero, `ticker` becomes the eyebrow, `author_name` becomes a 'By {name}' byline, `snapshot` renders as a mono-figure table, and `citations` become a table with clickable SEC EDGAR hyperlinks from `source_url`. It also confirms the `sections`+`citations` shape is interchangeable with create_report's output.

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 and artifact: 'Render a structured research brief into a professionally-styled Word document', then enumerates exactly what the output contains (masthead, body, snapshot table, citations table, footer). It also positions itself against siblings — complementary to generate_dcf_xlsx/generate_comps_xlsx, downstream of create_report — so an agent can distinguish it from render_report or save_freeform_report without opening a 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?

Gives an explicit call sequence ('typical flow is two tool calls: create_report → generate_research_brief_docx'), a named prerequisite ('Resolve each citation via verify_fact_lineage before publishing'), an alternative for a missing capability ('No embedded charts in v1; pair with generate_dcf_xlsx / generate_comps_xlsx'), and an entitlement gate ('Tier: pro+').

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.