Moltline Optimize

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

Annotations already establish that the tool is read-only, idempotent, non-destructive, and closed-world, but the description adds substantial behavioral detail beyond that: cost versus count optimization, CP-SAT optimality or FEASIBLE fallback, time-limit behavior, and the fact that invalid input returns an error object rather than a protocol error. It also explains that retrying after correction is safe.

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

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

The description is front-loaded with purpose, example, and usage boundary, and most sentences earn their place by conveying solver behavior, error handling, or sibling routing. It is information-dense but slightly overpacked, and the standalone 'FREE.' token adds little value.

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

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

Given the optimization complexity, the presence of an output schema, and the rich annotations, the description is complete: it covers objective, solver status, input limits, error format, retry safety, and the relevant sibling alternative. An agent has enough information to select and invoke it correctly.

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

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

Schema description coverage is already 100%, so the baseline is 3, but the description adds useful semantic context through a concrete example showing how stock, parts, and kerf are structured together. It also clarifies that stock cost drives the objective and that stock count is used when cost is absent, though it does not explicitly explain time_limit_s in prose beyond the solver time-limit concept.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific optimization resource: a least-waste 1D cut plan for bars, pipes, or boards, including saw kerf. It also explicitly distinguishes the tool from the sheet-cutting sibling by saying it is not for sheets and naming cutting_stock_2d.

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

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

It gives a concrete usage boundary (cut lists up to 200 pieces) and explicitly routes sheet-cutting use cases to cutting_stock_2d. That is both an inclusion condition and an alternative-tool exclusion.

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

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

Annotations cover readOnly/idempotent/destructive/openWorld, and the description adds substantial context beyond them: the guillotine edge-to-edge cut constraint, that grain true forbids rotation unless overridden per part, the heuristic (non-optimal) nature, and detailed non-throwing error behavior with a safe-retry guarantee.

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

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

Front-loads the purpose, then a compact input/output example, then constraints and error behavior. Dense and mostly waste-free, though the error-handling paragraph is somewhat verbose.

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

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

An output schema exists, and the description additionally shows a sample return shape with fill_pct, offcuts, unplaced. The guillotine/grain/kerf behaviors and error semantics are all covered, so an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the worked example input/output and the note that 'rotate overrides the grain rule per part' add semantics beyond the schema field descriptions. Marginal over baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Guillotine cut layouts for rectangular parts from sheets,' and clarifies kerf/grain handling. The '2D guillotine' framing distinguishes it from cutting_stock_1d and from general packing siblings like pack_bins.

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

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

Gives concrete use cases ('cabinet, sign and sheet-metal cut lists') and discloses the algorithm is a best-fit shelf heuristic, not optimal. Does not explicitly contrast with sibling tools like cutting_stock_1d, so it stops short of the explicit-alternatives bar.

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

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

Drops the annotations' boilerplate and adds genuine behavioral contract: it never raises a protocol error, returns {"error": ...} with a corrective message, and retry is always safe after fixing input. It also warns that road distances are longer by a non-uniform factor, which is the key modeling caveat an agent needs.

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

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

Front-loads what it is and that it is FREE, then example, then when-to-use, then error contract. Dense but every sentence carries information; the embedded JSON blobs make it visually heavy though compact in total length.

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

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

Despite an output schema existing, the description still sketches the return shape (matrix, unit, kind), and it covers input limits, error behavior, and retry safety. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is already 100% (km/mi enum-less unit, points up to 200), so the baseline is 3. The description exceeds that by showing a concrete points payload with id/lat/lon and a concrete matrix/unit response shape, which makes the required structure unambiguous.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource and its exact geometric basis: 'Straight-line (great-circle) distance matrix from coordinates', reinforcing it with 'kind: straight-line (haversine), not road distance'. This separates it cleanly from the road-routing siblings route_plan and route_plan_fleet.

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

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

Gives a clear positive condition ('no road matrix and a straight-line approximation is acceptable, or to sanity-check one') and an explicit exclusion ('Not road routing'). Slight gap: it describes the alternative conceptually rather than naming the sibling tools an agent should switch to.

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

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

Beyond the annotations, the definition discloses the error contract: it never raises a protocol error and instead returns {"error": ...}. It also adds retry guidance and a cost signal (“FREE”). The one repeated line about read-only and idempotent behavior is fine because the rest adds substantive context.

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

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

The purpose and the “FREE” signal are placed early, and every sentence adds useful information. The inline example response is somewhat redundant because an output schema exists, which keeps it from earning a 5.

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

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

The definition fully covers an agent's needs for a single required parameter: purpose, accepted inputs, usage, error behavior, and retry semantics. The output schema and annotations cover the rest.

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

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

Schema coverage is 100%, but the description still adds value: it shows the typical call shape, {"solution": <result of route_plan_fleet>}, and it explains which solver results are accepted and how they are recognized. That goes beyond the schema's generic “result object returned by one of this server's solve tools.”

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The definition uses a concrete verb and resource: a “plain-language summary of a solution from this server.” It lists the exact solver outputs it recognizes (route_plan, route_plan_fleet, pack_bins, and others), so an agent can tell it apart from every sibling without opening a schema.

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

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

The description states the use case directly: turning solver output into a message for a dispatcher or a shop floor. It also gives the key exclusion, “Not a re-solve,” and it constrains the input to results from this server's solve tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint and openWorldHint, so the bar is lower. The description still adds real value: it discloses that errors are returned as {"error": ...} objects rather than protocol errors, and that retry after correction is always safe. It does not discuss solver non-optimality/timeout behavior beyond the time_limit_s parameter.

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

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

Front-loaded with the core purpose and use cases, and the example is illustrative rather than padding. The inline JSON example is fairly long, but it earns most of its space by showing input/output shapes and slack/solver_status semantics.

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

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

For a solver tool with an output schema, nested objects and 100% schema coverage, the description covers purpose, input shape, an example return, error contract and retry safety. Nothing essential an agent needs to call it correctly is missing.

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

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

Schema coverage is already 100%, yet the description adds semantics not in the schema: any numeric item field named in limits is treated as a constrained resource, and qty allows repeated selection of an item. That is meaningful behavioural meaning beyond the field descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific operation (choose items maximising value under capacity limits) and a concrete resource model (items with value plus constrained fields). It also distinguishes scope from siblings like pack_bins/cutting_stock by stating what it is not for (dependencies between items).

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

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

Explicitly lists concrete use cases (budgets, cargo, campaign or feature selection) and an explicit exclusion ('Not for dependencies between items'). This gives an agent both positive selection criteria and a routing boundary.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world, so the description is free to add the things annotations cannot: the algorithm is a first-fit-decreasing heuristic and explicitly not proven optimal, and invalid input never raises a protocol error but returns {"error": ...}. That optimality caveat and the error contract materially change how an agent should interpret and retry results.

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

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

Purpose and limits are front-loaded and every later sentence (rotation modes, support rule, freight use case, optimality caveat, error contract) carries distinct information. The embedded input/output JSON is longer than strictly necessary given a full schema and an output schema, but it does resolve the free-form object shapes, so it mostly earns its space.

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

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

For a nested, free-form-schema tool this covers what an agent actually needs: the size ceiling, unit consistency requirement, rotation and support semantics, the heuristic's non-optimality, the in-band error shape, and retry safety. Return values are shown in the example and further backed by an output schema, so nothing material is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description earns extra by defining semantics the schema only names: rotation modes with "upright (rotate around the vertical axis only)", "fragile items carry nothing", and rules.min_support as the share of a box's base that must rest on the floor or on boxes below, default 0.6. The worked example also disambiguates the free-form item and container objects.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Place up to 20 boxes into containers or pallets") plus the constraints it honors (rotation, weight, support). The 20-box cap also implicitly separates it from the sibling pack_bins_large, so an agent can pick between them 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.

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

"Use to decide pallet or carton count before booking freight" gives a concrete decision context rather than a generic restatement. It does not explicitly name pack_bins_large as the alternative for larger problems or state when-not to use it, so it stops short of full routing guidance.

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

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

Annotations already cover read-only/idempotent/no-destruction, yet the description adds material context beyond them: invalid input never raises a protocol error but returns {"error": ...}, and retrying after a fix is always safe. It also honestly discloses the heuristic and its non-optimality (first-fit decreasing on extreme points), which is exactly the kind of quality caveat annotations cannot carry.

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

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

Front-loaded with the differentiating sentence first, then the example, then behavior and error contract. The inline example is verbose but earns its place for a nested payload; a line or two could still be trimmed.

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

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

For a nested-object optimization tool it covers the error contract, retry safety, solution quality, and output shape; an output schema exists so return values needn't be spelled out. The one soft spot is deferring the result shape to "same as pack_bins" rather than describing it locally.

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

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

Schema description coverage is 100%, so the baseline applies; the worked example restates the same item/container field names the schema already documents. The example does helpfully illustrate the nested payload shape, but it omits the optional `rules` parameter entirely, so it adds little semantic meaning the schema lacks.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names the specific operation (bin packing), pins down its capacity envelope (up to 300 item units, 200 containers), and explicitly anchors it to sibling pack_bins as the same packer at larger scale. An agent can distinguish it from pack_bins and from the cutting_stock/knapsack siblings without opening a schema.

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

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

Gives concrete use cases ("order consolidation and load planning") and implies the pack_bins vs pack_bins_large selection rule via the stated capacity limit. It never states an explicit exclusion or a fallback for oversized problems, which keeps it just 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.

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

Annotations already declare readOnly, idempotent and non-destructive, and the description layers genuinely non-obvious behavior on top: the objective is lexicographic (fill slots, then spread hours, then preferences), solver_status is returned, errors never surface as protocol errors but as {"error": ...}, and retry after correcting input is safe. Licensing and scale limits are disclosed too.

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

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

The core purpose and the PREMIUM flag are front-loaded, and every subsequent sentence adds new information. The inline JSON examples make it a dense single block rather than a structured section list, which costs a little scannability, but there is no wasted prose.

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

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

For a nested 4-parameter solver with an output schema, this covers everything an agent needs: input shape, objective ordering, response fields, error contract, scale ceilings, and license gating. Nothing required to call it correctly is absent.

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

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

Schema coverage is 100%, so baseline would be 3; the description goes further with a worked input payload and an explanation of how fields interact — 'prefer'/'avoid' shift ids feed the third objective tier, 'weight' and 'skill' affect slot filling. It still leaves some fields (min_hours, max_shifts) to the schema, so not a full 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb-plus-resource plus the constraint set it honours: 'Assign staff to shifts under availability, skills, hour caps and rest gaps.' That framing is unmistakably a shift-scheduling solver, which no sibling (bin packing, routing, knapsack, cutting stock) covers, so an agent can route correctly without opening a schema.

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

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

Gives concrete operating context — 'Use for weekly rotas of up to 60 staff and 150 shifts' — and an explicit exclusion: 'Not a determination of labour-law compliance: the rules are the ones you pass.' It also names the PREMIUM license gate. It stops short of routing to siblings such as validate_problem or explain_solution, which is the only missing piece.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description still adds non-obvious behavior: it never raises a protocol error, returns a structured {"error": ...} object on bad input, and is therefore always safe to retry after correction. It also discloses the 12-stop ceiling and that costs can be in arbitrary units. Minor deduction because the full input/output example overlaps with what the existing output schema already provides.

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

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

The most decision-relevant facts (what it does, cost, stop cap) are front-loaded before the example. The single dense paragraph carrying example JSON, matrix rules, exclusions, and error semantics is efficient but harder to scan; a light break would improve it.

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

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

Covers everything needed to invoke correctly: required inputs, matrix shape and depot convention, the 12-stop limit, capacity extension, sibling routing, and error/retry semantics. With an output schema present, the description is not obligated to explain return values further, and it still sketches them.

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

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

Schema coverage is 100%, so baseline is 3; the description earns more by explaining that the matrix is in the caller's own units (km, minutes, cost), must be square, and that pairing optional per-stop demand with vehicle_capacity upgrades the call into a capacity check — a relationship the schema fields state only in isolation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opening sentence states a precise verb and resource — 'Order up to 12 stops into the shortest single-vehicle route on your distance matrix' — including the scale cap and the required input type. It is immediately distinguishable from route_plan_fleet, which it names explicitly for the multi-vehicle case.

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

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

Gives both positive scope ('one driver's day or a courier's loop') and explicit exclusions ('Not for several vehicles or time windows: use route_plan_fleet'), plus a dependency alternative ('call distance_matrix_haversine for straight-line values'). An agent can route itself without inspecting any sibling schema.

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

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

Annotations already cover readOnly/idempotent/non-destructive, yet the description still adds real value: PREMIUM license gating, the 200-stop ceiling, the never-raises-protocol-error contract with the {"error": ...} payload shape, and explicit retry safety after correcting input. It also discloses solver outcomes (FEASIBLE, unserved list) and the time_matrix fallback rule.

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

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

Front-loaded with the one-line capability statement, followed by a worked example and then behavioral caveats — logically ordered with no filler sentences. The inline JSON example is long but carries real signal about the nested stop/vehicle shape, so the length is largely earned.

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

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

For a 7-parameter solver tool, the definition covers modeling semantics, a worked input/output sample, error behavior, and runtime budget. An output schema exists so return values need not be explained, and the brief return sketch is harmless redundancy rather than a gap.

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

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

Schema coverage is already 100%, so baseline is 3, but the description adds meaning the schema lacks: windows and service_min are minutes from the start of the day, and if time_matrix is absent the distance matrix is read as minutes. drop_penalty's INFEASIBLE tradeoff is also explained beyond the schema's one-liner.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource with scope: 'Capacitated, time-windowed routing for a fleet over up to 200 stops.' That concretely distinguishes it from route_plan (single-vehicle) by the word 'fleet' and the stop cap, though it never names the sibling explicitly.

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

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

'Use for daily dispatch' gives the intended context, and 'Set drop_penalty to allow stops to be left unserved at that cost instead of returning INFEASIBLE' tells the agent how to handle a key modeling decision. 'Not a map service; bring your own matrices' steers callers toward the matrix sibling without naming it, so the routing-vs-matrix split is implied rather than spelled out.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description adds real context beyond them: it is FREE, never raises a protocol error, returns a {"error": ...} object instead, and is safe to retry after correction. This is exactly the supplementary behavioral detail the annotations cannot express.

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

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

Front-loaded with purpose and cost, then examples and error behavior. The worked example is somewhat verbose but each line (input shape, return shape, types, error format) carries actionable information, so little is wasted.

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

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

Given a nested-object input and an output schema, the description still supplies concrete return-field semantics (ok, issues, size, tier_hint) and explicit error behavior, which is more than enough for correct invocation.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds a concrete typical input example and explains that the problem object uses the same fields as the matching tool, which meaningfully clarifies how to populate the nested 'problem' parameter. That is a step above what the schema alone conveys.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action on a specific resource ('Check a problem's shape and obvious feasibility') and explicitly disclaims what it is not ('Not a solve: it never calls the solver'), cleanly separating it from all the solver siblings. An agent can tell exactly what this does without opening the schema.

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

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

Gives an explicit trigger ('Use first when an agent has assembled the problem from other data') and routes the agent onward via tier_hint to the matching sibling (e.g. route_plan_fleet). Both the when and the next step are named, leaving nothing to inference.

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