duffel-recovery

Overview Schema Source Related Servers Discussions Admin

score_options

Score and rank disrupted-flight recovery options using transparent cost math—cash paid, refunds, credits, and arrival delay—so you can identify the lowest-cost choice that meets the deadline.

Instructions

Score and rank options with the traveler's objective. Do the math here, not in your head.

    total_cost = cash_paid - cash_refunded - credit x credit_value_factor + hours_late x value_of_time.
    It is a COST, so lower is better; say that whenever you show it to the traveler.
    Options missing the deadline or over the spend cap can't be the pick. Every amount and time
    must cite the call_id it came from; numbers that don't appear there are rejected.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`options`	Yes
`deadline_local`	Yes
`original_arrival_local`	Yes
`original_arrival_call_id`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 21, 2026

TDQS

A4.1/5.0

Behavior4/5

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

It discloses the exact total_cost formula, states that lower cost is better and should be communicated to the traveler, and warns that options past deadline/over cap cannot be chosen and uncited numbers are rejected. This goes beyond the annotations; only the source of value_of_time and credit_value_factor is left underspecified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the tool's purpose and every sentence adds operational guidance: the formula, the lower-is-better instruction, the invalid-option conditions, and the citation requirement. No filler or repetition of schema content.

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?

It covers the core scoring mechanics and rejection rules, and the output schema can explain return values. But an agent cannot fully determine the required computation on its own because the source of value_of_time, credit_value_factor, and spend cap is never stated, and the relationship between formula variables and parameters is only implied.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With schema description coverage reported at 0%, the description must compensate for parameter meaning, and it partially does: cash_paid, cash_refunded, credit, deadline, and call_id requirements map to the schema. However, it does not name the parameters explicitly, omits the mapping of credit to credit_received and hours_late to original_arrival_local, and never explains where credit_value_factor, value_of_time, or the spend cap come from.

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?

The opening line names a specific verb and resource: score and rank options against the traveler's objective. The cost formula and constraints make the tool's job unmistakable and separate it from siblings like search_alternatives or book_offer, which find or execute options rather than evaluate them.

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?

The description gives clear context: use this tool to do the ranking math rather than computing it mentally, with deadline and spend-cap constraints governing which option can be picked. It does not name explicit alternatives or when-not conditions, so it falls short of a 5.

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

Deploy Server