Skip to main content
Glama

Reconcile durable facts against live state, then rank the day (deterministic)

reconcile_and_rank

Reconciles keyed brain facts with live task state, then ranks the day in one deterministic pass. Returns the recomputed plan, applied overrides, and unresolved conflicts for user review.

Instructions

Use this INSTEAD of rank_day when a durable brain fact might override live task state — it reconciles then ranks in one deterministic pass, so nothing relies on you remembering to reconcile. Pass the same inputs as rank_day (tasks/events/busy/now/timezone) PLUS overrides: keyed brain claims (each entityKey like todoist:task:<id>, a field such as priority or due, its brain value, slotType = intent when the brain is authoritative (a deliberate override) or state when it's just a remembered value, plus the fact's at/sourceClass). Returns {plan, applied, flags}: plan is the recomputed daily plan (built FROM the reconciled values); applied lists overrides that won and changed the plan (mention them to the user); flags are genuine contradictions the code would not auto-resolve — ASK the user about each, don't guess. Unkeyed prose facts are not reconcilable here (by design) — leave them out of overrides.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "tasks": "<tasks>",
      "events": "<events>",
      "now": "<now>",
      "timezone": "<timezone>"
    },
    "name": "reconcile_and_rank"
  }
}

Input Schema

NameRequiredDescriptionDefault
nowYesCurrent instant (RFC3339), e.g. from get-current-time.
busyNoOptional busy intervals (e.g. from get-freebusy), ISO 8601.
tasksYesTodoist tasks to rank (same shape as rank_day).
eventsYesFixed calendar events for the day.
timezoneYesIANA timezone, e.g. America/New_York.
overridesNoKeyed brain claims that may override a live task field before ranking. Usually empty.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.1

TDQS

A4.8/5.0
Behavior5/5

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

No annotations are supplied, so the description carries the full burden and does: it discloses determinism ('one deterministic pass'), the exact return shape `{plan, applied, flags}` with the meaning of each field, and the required agent behavior for `flags` (genuine contradictions the code will not auto-resolve). It even states why the tool exists behaviorally — so nothing relies on the agent remembering to reconcile.

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-loads the routing decision and then moves through inputs and returns in a logical order with no filler sentences. It is a single dense paragraph, though, and the mid-sentence parentheticals make it slightly harder to scan than a short bulleted structure would be.

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 6-parameter compute tool with no output schema, the description supplies what the schema cannot: the return contract (`plan` built from reconciled values, `applied`, `flags`) and the required follow-up behavior. Nothing an agent needs in order to call it and act on the result 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 coverage is 100%, so the baseline is 3; the description goes further by explaining the reconciliation semantics of `slotType` — `intent` means the brain is authoritative and wins, `state` means the live value wins — plus the `entityKey` convention (`todoist:task:<id>`) and the `field` values (`priority`, `due`). It does not repeat the `at`/`sourceClass` provenance meaning, which the schema already documents.

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 compound verb pair (reconcile + rank) on a specific resource (durable brain facts vs live task state) and immediately names the sibling it replaces: 'Use this INSTEAD of rank_day when a durable brain fact might override live task state'. An agent can distinguish it from rank_day without opening either 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 selection rule versus rank_day, an explicit exclusion ('Unkeyed prose facts are not reconcilable here (by design) — leave them out of `overrides`'), and post-call guidance (mention `applied` to the user; ASK about each flag rather than guessing). Nothing is left to inference.

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