Skip to main content
Glama
ferinator

Bullrun

by ferinator
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Create a position draft

create_position_draft

Recommend stocks or ETFs to add to an existing portfolio and save them as reviewable draft positions in Bullrun, so you can accept or discard ideas before any holdings change.

Instructions

Use when the user asks what to BUY or ADD to an EXISTING portfolio — e.g. "what should I buy next", "suggest a stock or ETF for my portfolio", "what should I add", "recommend a position", "any ideas to round out my holdings". Generates REVIEWABLE suggested additions for one existing Bullrun portfolio. Requires OAuth with the write:drafts scope. Available to signed-in free accounts; daily usage limits and portfolio capacity still apply. This is DRAFT-ONLY: the suggested position(s) are saved to the user's account and appear in the Bullrun Portfolio tab under Pending AI drafts, where the user reviews and accepts them into the target portfolio or discards them. It never changes live holdings by itself. To draft a whole new portfolio from scratch use create_portfolio_draft; to test whether a specific named ticker fits, use get_portfolio_analytics with candidateTicker. Pass instrumentUniverse for stocks only, ETFs only, or a mix. If it is unclear, first confirm which portfolio (use list_portfolios when the user has more than one) and how many ideas (a single best idea or a few) in ONE quick step; otherwise just build.

Input Schema

NameRequiredDescriptionDefault
portfolioIdYesThe Bullrun portfolio id to propose additions for. Use list_portfolios first if unsure.
maxPositionsNoHow many suggested additions to save, 1-5. Use 1 for a single-position idea; default 3.
instrumentUniverseNoCandidate universe: stocks only, ETFs only, or a mix. Default mix.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.7.0
    • addedInput schema / properties / instrumentUniverse
      Added value: +{
+  "description": "Candidate universe: stocks only, ETFs only, or a mix. Default mix.",
+  "enum": [
+    "stocks",
+    "etfs",
+    "mix"
+  ],
+  "type": "string"
+}
  2. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Goes well beyond the annotations by disclosing the OAuth scope (write:drafts), free-account availability, daily usage limits, and portfolio capacity constraints. It also defines the write's actual blast radius: drafts land in Pending AI drafts for review and 'never changes live holdings by itself', which resolves the ambiguity left by readOnlyHint=false with destructiveHint=false.

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 trigger condition and user phrasings before any mechanics, and every later sentence carries a distinct fact (scope, limits, draft semantics, alternatives, clarification rule). It is dense rather than padded, though the length pushes toward the upper bound of what an agent wants to read before a call.

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 non-destructive write with no output schema, the description covers what an agent needs: auth requirements, quota constraints, where the result surfaces, and that the user must explicitly accept it. Return-value detail is unnecessary because the post-call state is described behaviorally (drafts appear under Pending AI drafts).

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 100%, so the structured fields already carry the parameter meaning. The description still adds intent mapping the schema lacks: 'a single best idea or a few' ties maxPositions to user phrasing, and 'Pass instrumentUniverse for stocks only, ETFs only, or a mix' frames the enum as a decision an agent must make rather than a raw value list.

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 resource ('Generates REVIEWABLE suggested additions for one existing Bullrun portfolio') with the scope narrowed to additions to an EXISTING portfolio. It explicitly contrasts with create_portfolio_draft and get_portfolio_analytics, so an agent can separate it from the nearest siblings without opening schemas.

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?

Opens with 'Use when the user asks what to BUY or ADD...' and supplies four concrete user phrasings that trigger it. It names two alternatives with the conditions that select them (whole new portfolio -> create_portfolio_draft; testing a named ticker -> get_portfolio_analytics) and prescribes a single-step clarification flow with list_portfolios.

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

Deploy Server

Other Tools