Skip to main content
Glama

Rank candidates

acubic_rank_candidates

Ranks the candidates of a design before anything is saved (Order & Select on acubic.ai): the ranked list, page by page, with score, per-factor values (vs industry: also the peers' median), sector, country and asset class, and the pick the site would make. A fresh ranking uses one portfolio generation. The list is kept 1 hour under candidates_id: paging, previewing a pick or re-ranking it cost nothing more, and acubic_create_strategy saves the pick, once per weighting you want to compare. It saves nothing. To count names that pass filters use acubic_screen_universe.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "acubic_rank_candidates"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoRows per page.
cursorNoA previous next_cursor.
localeNoThe language of this conversation.
includeNoIds per acubic_list_strategy_options section (index: indices).
rankingNoA preset: card (acubic_list_strategy_templates). The engine: rank_method or rank_blend. With candidates_id: re-rank that pool.
regionsNo
sectorsNo
recipe_idNoA recipe id (acubic_list_strategy_options, recipes): sets ranking, sectors, allocation and asset count unless given; your filter_rules add to its own.
experienceNoLegacy: beginner or intermediate with risk_level selects a preset; prefer template_id. Omit for an engine build.
risk_levelNoPreset only (legacy path): largest acceptable drawdown; prefer template_id.
asset_countNoNumber of assets.
template_idNoAn id from acubic_list_strategy_templates: a preset, or advanced for the engine.
filter_rulesNoEach rule: metric, op, value in the metric's own unit.
select_countNoTop N to select (10, 15, 20, 30 or 50 within the count range; see selection.select_counts). Not with selected_symbols.
asset_classesNo
candidates_idNoA ranked list from acubic_rank_candidates (valid 1 hour).
custom_symbolsNoTickers to add to the pool, checked as on acubic.ai.
locked_symbolsNoAlways selected, exempt from every filter.
position_sizingNoDefault: the sizes recommended for the number of assets.
response_formatNoconcise
excluded_symbolsNoNames removed from the screened pool (Step 1).
selected_symbolsNoPreview a hand-picked selection of candidates_id (not with allocation or correlation limits).
selection_limitsNoMin/max share of the selection per sector, country or asset class.
asset_count_rangeNoInstead of asset_count (default 15 to 25).
client_request_idNoIdempotency key.
correlation_limitNoNot offered yet: omit it unless acubic_list_strategy_options shows it offered; then 0.50-0.95, step 0.05 (preset: 0.80).
class_position_sizingNoPer-asset-class sizes overriding position_sizing.

Output Schema

NameRequiredDescriptionDefault
rowsNo
errorNo
countsNo
quotasNo
statusNo
rankingNo
progressNo
selectionNo
truncatedNo
disclosureNo
experienceNo
expires_atNo
risk_levelNo
next_cursorNo
candidates_idNoThe kept ranked list; acubic_create_strategy and this tool accept it for 1 hour.
custom_symbolsNo
client_request_idNoThe idempotency key this call used (yours, or one made for it). Repeat the call with it to get the same run without a second charge.
quota_unavailableNoTrue when the quota counters could not be read after the work was saved; the work is saved.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4/5.0
Behavior3/5

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

Adds real operational context beyond the annotations: a fresh ranking burns one portfolio generation, the candidate list lives 1 hour under candidates_id, paging and re-ranking are free, and nothing is persisted — which explains why readOnlyHint is false despite 'saves nothing'. It does not cover what happens when candidates_id expires or how errors surface mid-paging.

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 purpose, then cost model, then cache semantics, then the sibling handoff — a sensible order. Some parentheticals, such as '(vs industry: also the peers' median)' and the 'Order & Select on acubic.ai' aside, add bulk without much decision value.

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

Completeness3/5

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

For a 27-parameter tool, an output schema, and a non-read-only annotation, the description covers the quota, caching, and non-persistence story well. It leaves out pagination termination behavior, what happens after the 1-hour window, and whether generation quota is consumed when re-ranking or previewing with an existing candidates_id.

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 85%, so the baseline is 3, and the description goes further by explaining the candidates_id lifecycle (valid 1 hour, reusable for paging/preview/re-rank without extra cost) and that each weighting to compare needs its own save path. It still treats ranking and weighting arguments in prose rather than adding precision beyond 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?

States a specific verb and resource (ranks the candidates of a design) plus the exact payload: ranked list page by page, score, per-factor values, sector, country, asset class, and the site's pick. It draws a sharp line against the two closest siblings by naming them: it 'saves nothing' unlike acubic_create_strategy, and counting filtered names belongs to acubic_screen_universe.

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

Usage Guidelines4/5

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

Gives clear routing: use acubic_create_strategy to persist a pick, acubic_screen_universe to count names passing filters, and re-rank via candidates_id rather than spending a new generation. It does not spell out an explicit 'do not call this when…' case beyond the save/count split.

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.

Resources