builtin__rank

Ranks a whole list against a question in one decision-model call.

Behavior

• The items become the options of one choice question, state is the context they’re judged against, and instructions is the question.
• Each option shows the item’s describe field, or the whole item when describe is absent.
• items is the list sorted by probability, highest first, and ranked pairs each item with its probability. Both are cut to top_k.
• Options are shown in a shuffled order seeded from the items, since decision models lean toward the first options. The same list ranks the same way on a rerun.
• none adds a “nothing fits” option. Its probability comes back as none, and no_fit is true when it beats every item.
• Lists over 254 items are ranked in chunks sent together, and each chunk’s best meet in a final choice. Items that don’t reach the final choice follow the finalists with a null probability.
• Needs a decision model role, decider by default.

When to use it

• Reranking search results, candidates or options against a question: one call instead of one per item, and no LLM.
• Keep state to what the question needs: the question and its context, not the items.
• For an absolute yes or no per item rather than an order, use a filter step with a decide gate.

Available to	Effect
Any agent or plan step	Read-only

Input

describe · string

Dot path into each item to show as the option, e.g. url or meta.date

instructions · string · required

The choice question

items · any[] · required

The list, usually a template like {{E1.results}}

model · string

The decision model role; default decider

none · string

Text of a ‘nothing fits’ option

state · any · required

The context the items are judged against, e.g. {“question”: “{{input.question}}”}

top_k · integer

Keep only the best k

Output

items · any[] · required

no_fit · boolean

none · number

ranked · object[] · required

Plan step

- id: E1
  tool_name: builtin__rank
  input:
    state: "{{input.state}}"
    items: "{{input.items}}"
    instructions: "{{input.instructions}}"