Describe the strategy model

Operation id: describe_portfolio_model — REST POST /api/v1/research/describe_portfolio_model, MCP tool describe_portfolio_model.

When should you use Describe the strategy model?

• Before creating or editing a strategy, to know every field it can set and the limits of the user's plan.
• The user asks what a setting means, what its default is, or how far it can go.

Use another operation when:

• You only need the allocation methods and their own parameters — use list_allocation_methods instead.

What parameters does Describe the strategy model take?

• section (optional; string; one of overview, portfolio, risk_conditions, allocation, models, position_exits, selection, user_settings; default "overview") — The section to describe: overview lists the sections; portfolio (the Combined level), risk_conditions, allocation, models (the strategies inside a Combined), position_exits, selection or user_settings (the simulation settings).

What does Describe the strategy model return?

The result object holds the fields below. Every result also carries a text summary, the assumed values and the dataVersion, as the reference describes.

• section (string; one of overview, portfolio, risk_conditions, allocation, models, position_exits, selection, user_settings) — The section described.
• title (string; at least 1 characters) — The section's title, in the product's words.
• summary (string; at least 1 characters) — What the section controls, in one or two sentences.
• fields (list) — Every field of the section, in the order the app shows them; empty for the overview.
• fields[].path (string) — The field's public path in a strategy definition, the path creating and editing a strategy use.
• fields[].name (string; at least 1 characters) — The field's name as the app shows it.
• fields[].type (string; one of number, integer, boolean, enum, string, list, object) — number, integer, boolean, enum, string, list or object.
• fields[].unit (string; one of none, number, count, days, weeks, months, quarters, years, reports, bars, fraction, percent, multiple, sharpe_points, sigma, usd, base_currency, date, native) — The unit of the field's value. (convention fraction)
• fields[].default (number / boolean / string; may be null; unit: the unit of what it describes) — The value used when the field is not given. (convention native_unit)
• fields[].enabledByDefault (boolean; may be null) — For a field that can be switched on or off, whether it is on by default; null for any other field.
• fields[].min (number; may be null; unit: the unit of what it describes) — The smallest value the product allows, or null. (convention native_unit)
• fields[].max (number; may be null; unit: the unit of what it describes) — The largest value the product allows, or null. (convention native_unit)
• fields[].values (list; may be null) — The values the app offers for an enum field, or null. Where the app locks a choice, only the locked value is listed: two risk conditions are combined with or, and the rebalance cadence is month.
• fields[].steps (list; may be null; unit: the unit of what it describes) — The only numbers the field accepts, ascending, such as the starting capital's fixed amounts; null when any number between min and max is accepted. (convention native_unit)
• fields[].boundsBy (object; may be null) — Bounds that depend on another field, one case per value of that field, such as a risk rule's threshold by the metric it reads; null when the bounds are fixed. The field's own unit, default, min and max are those of the other field's default value.
• fields[].boundsBy.on (string) — The public path of the field whose value decides the bounds.
• fields[].boundsBy.cases (list) — One entry per value of that field.
• fields[].boundsBy.cases[].when (string; at least 1 characters) — The value of the deciding field this case applies to.
• fields[].boundsBy.cases[].unit (string; one of none, number, count, days, weeks, months, quarters, years, reports, bars, fraction, percent, multiple, sharpe_points, sigma, usd, base_currency, date, native) — The unit of the field's value in this case. (convention fraction)
• fields[].boundsBy.cases[].default (number / boolean / string; may be null; unit: the unit of what it describes) — The default in this case. (convention native_unit)
• fields[].boundsBy.cases[].min (number; may be null; unit: the unit of what it describes) — The smallest value allowed in this case, or null. (convention native_unit)
• fields[].boundsBy.cases[].max (number; may be null; unit: the unit of what it describes) — The largest value allowed in this case, or null. (convention native_unit)
• fields[].boundsBy.cases[].steps (list; may be null; unit: the unit of what it describes) — The only numbers accepted in this case, ascending; null when any number between this case's min and max is accepted. (convention native_unit)
• fields[].valuePlans (list; may be null) — The values that need a higher plan than the field itself, such as the advanced covariance estimators; null when every value comes with the field.
• fields[].valuePlans[].value (string; at least 1 characters) — One of the field's values.
• fields[].valuePlans[].includedInYourPlan (boolean) — True when your current plan includes this value.
• fields[].valuePlans[].lowestPlan (string; one of free, starter, advanced, ultimate, professional; may be null) — The lowest plan that includes this value, or null when no plan includes it today.
• fields[].planLimit (object; may be null) — Your plan's limit on the field, or null when no plan limits it.
• fields[].planLimit.includedInYourPlan (boolean) — True when your plan lets you use the field.
• fields[].planLimit.lowestPlan (string; one of free, starter, advanced, ultimate, professional; may be null) — The lowest plan that lets you use the field, or null when no plan lets you use it today.
• fields[].planLimit.yourMin (number; may be null; unit: the unit of what it describes) — Your plan's floor for a number field, such as the earliest starting year your plan allows, which can be higher than min; null when your plan sets none. (convention native_unit)
• fields[].planLimit.yourMax (number; may be null; unit: the unit of what it describes) — Your plan's ceiling for a number field, which can be lower than max; null when your plan sets none. (convention native_unit)
• sections (list) — Every section of the model, to navigate from.
• sections[].id (string; one of overview, portfolio, risk_conditions, allocation, models, position_exits, selection, user_settings) — The section's id, to pass as section.
• sections[].title (string; at least 1 characters) — The section's title.

What does a call to Describe the strategy model look like?

The position exits of a strategy, for a caller whose plan caps positions

Asked as: How low can I set a stop loss?

# Caller on the starter plan
POST /api/v1/research/describe_portfolio_model
Authorization: Bearer <API key or access token>
Content-Type: application/json

{
  "section": "position_exits"
}

The result:

{
  "section": "position_exits",
  "title": "Position exits",
  "summary": "Rules that close positions inside each strategy: a maximum holding time, a delay before reinvesting, a cap on open positions, a take profit and a stop loss. Each can be switched on or off.",
  "fields": [
    {
      "path": "models[].positionExits.maxHoldMonths",
      "name": "Max hold months",
      "type": "integer",
      "unit": "months",
      "default": 12,
      "enabledByDefault": false,
      "min": 1,
      "max": 120,
      "values": null,
      "steps": null,
      "boundsBy": null,
      "valuePlans": null,
      "planLimit": null
    },
    {
      "path": "models[].positionExits.reinvestDelayMonths",
      "name": "Reinvest delay",
      "type": "integer",
      "unit": "months",
      "default": 12,
      "enabledByDefault": false,
      "min": 1,
      "max": 120,
      "values": null,
      "steps": null,
      "boundsBy": null,
      "valuePlans": null,
      "planLimit": null
    },
    {
      "path": "models[].positionExits.maxPositions",
      "name": "Max positions",
      "type": "integer",
      "unit": "count",
      "default": 10,
      "enabledByDefault": true,
      "min": 1,
      "max": 50,
      "values": null,
      "steps": null,
      "boundsBy": null,
      "valuePlans": null,
      "planLimit": {
        "includedInYourPlan": true,
        "lowestPlan": "free",
        "yourMin": null,
        "yourMax": 10
      }
    },
    {
      "path": "models[].positionExits.takeProfit",
      "name": "Take profit",
      "type": "number",
      "unit": "fraction",
      "default": 1.5,
      "enabledByDefault": false,
      "min": 0.05,
      "max": 10,
      "values": null,
      "steps": null,
      "boundsBy": null,
      "valuePlans": null,
      "planLimit": null
    },
    {
      "path": "models[].positionExits.stopLoss",
      "name": "Stop loss",
      "type": "number",
      "unit": "fraction",
      "default": -0.3,
      "enabledByDefault": false,
      "min": -1,
      "max": -0.05,
      "values": null,
      "steps": null,
      "boundsBy": null,
      "valuePlans": null,
      "planLimit": null
    }
  ],
  "sections": [
    {
      "id": "overview",
      "title": "Overview"
    },
    {
      "id": "portfolio",
      "title": "Combined level"
    },
    {
      "id": "risk_conditions",
      "title": "Risk conditions"
    },
    {
      "id": "allocation",
      "title": "Allocation"
    },
    {
      "id": "models",
      "title": "Strategies"
    },
    {
      "id": "position_exits",
      "title": "Position exits"
    },
    {
      "id": "selection",
      "title": "Selection"
    },
    {
      "id": "user_settings",
      "title": "Simulation settings"
    }
  ]
}

The summary it returns:

Position exits: 5 fields. Max positions is on by default and capped at 10 by your plan; the other four are off until you set them.

What goes wrong most often with Describe the strategy model?

• Take profit and stop loss are fractions: 1.5 is +150% and -0.3 is -30%, while the app shows them as percentages.
• A number field can have two ceilings and two floors: max and min are the product's, planLimit.yourMax and planLimit.yourMin your plan's; the tighter one applies. A field with steps accepts those numbers only, and a field with boundsBy takes the bounds of the case its deciding field selects.
• Position exits apply inside each strategy (the API's model), not to the Combined as a whole.

Which error codes can Describe the strategy model return?

Describe the strategy model has no error codes of its own beyond the common ones.

Every operation can also return the common error codes listed in the reference.

Which plans include Describe the strategy model?

Describe the strategy model belongs to the Strategy authoring family of operations and counts as one research call against your plan's monthly allowance. Which families your plan includes, and how large its allowances are, is set out in What each plan includes.