MCP tools
What an assistant connected to foil.tools can call. A Claude, ChatGPT or Grok connector and a script carrying an ft_ key reach the same endpoint, https://foil.tools/api/mcp, and are offered the same 21 tools. The list below is generated from the server at build time, so it is the list a client receives from tools/list, not a copy of it. Connect your agent is the setup; this page is what you get once it is connected.
Three columns need a word. Access is what a call can touch: most tools only read the public library or compute, a few read what is already saved in your account, and three write to it (they only ever add; nothing deletes or overwrites). Metered marks the tools that can draw on your account's monthly allowance and, after it, on whatever the account is paying for; each tool's own description says how. Everything else is free, though the free analysis is rate-limited.
A connected client does not see a new tool until it reconnects. Clients cache tools/list when they connect, and this server is stateless, so it has no session to push a tools/list_changed notification down. If a tool on this page is missing from your assistant, disconnect the connector in your assistant's settings and connect it again.
Every tool
| Tool | Access | Metered | Does |
|---|---|---|---|
| search_airfoils | read-only | no | Search the foil.tools library of ~1,600 airfoils by name substring, family, thickness and camber range. |
| get_airfoil | read-only | no | Get one airfoil by name: family, source, geometry summary (thickness/camber and their chordwise locations, TE thickness) and CST parameters. |
| get_polar | read-only | no | Get stored aerodynamic polars (lift/drag/moment curves) for an airfoil from the foil.tools database. |
| search_by_operating_point | read-only | no | Rank database airfoils by drag at a single operating point (CL, Re), interpolating each stored polar at the target CL. |
| find_airfoil | read-only | no | Multi-point airfoil selector: scores every database airfoil against a weighted set of operating points (Re, CL pairs) and returns the top 10, with per-point matched drag/alpha/moment. |
| analyze_airfoil | read-only | no | Run NeuralFoil 2D analysis to generate fresh polars (alpha, CL, CD, CM) for an airfoil at given Reynolds numbers. |
| optimize_airfoil | read-only | yes | Shape optimization of an airfoil’s CST parameters (a NeuralFoil population search, then IPOPT gradient refinement) to minimize weighted drag across one or more operating points (Re, CL), with optional geometric constraints. |
| analyze_wing | read-only | yes | Analyze a 3D wing (AeroSandbox AeroBuildup strip theory, or VLM) defined by spanwise stations. |
| purchase_credits | not read-only | no | Create a Stripe Checkout URL to buy a credit pack for the account this session is authenticated as. |
| search | read-only | no | Search the foil.tools airfoil library by name, family, or free text and return matching airfoils with their identifiers and links. |
| fetch | read-only | no | Retrieve the full record for one airfoil by the identifier returned from the search tool: geometry, stored aerodynamic polar summary, and a link to its page on foil.tools. |
| save_airfoil | writes to your account | no | Save an airfoil to the signed-in foil.tools account so it appears under Dashboard → Foils and can be opened, plotted and exported later. |
| save_wing_design | writes to your account | no | Save a wing design to the signed-in foil.tools account so it appears under Dashboard → Wings and opens in the wing designer. |
| save_wing_analysis | writes to your account | no | Save the results of an analyze_wing run to the signed-in foil.tools account, so it appears under Dashboard → Wing Analyses. |
| list_saved_airfoils | reads your account | no | List the airfoils saved on the signed-in foil.tools account (Dashboard → Foils), newest first. |
| get_saved_airfoil | reads your account | no | Get one airfoil saved on the signed-in account by its id, with the geometry it was stored with — CST parameters for a kulfan foil, coordinates for a dat one. |
| list_wing_designs | reads your account | no | List the wing designs saved on the signed-in foil.tools account (Dashboard → Wings), newest first. |
| get_wing_design | reads your account | no | Get one wing design saved on the signed-in account by its id, as the full designer document — the parametric planform plus the spline channels that carry a curved or elliptical shape. |
| list_wing_analyses | reads your account | no | List the wing analyses saved on the signed-in foil.tools account (Dashboard → Wing Analyses), newest first. |
| get_wing_analysis | reads your account | no | Get one wing analysis saved on the signed-in account by its id, with the full stored results — the polar, the spanwise loading, whatever the run produced. |
| analyze_trim | reads your account | yes | Trim an aircraft: a wing plus a stabiliser (and any further surfaces) about a CG, solved together on AeroSandbox LiftingLine so the stabiliser flies in the wing's downwash. |
search_airfoils
Search airfoils · read-only · not metered
Search the foil.tools library of ~1,600 airfoils by name substring, family, thickness and camber range. Returns name, family, source, thickness and camber (as fractions of chord) for each match. Free.
| Input | Type | Required | Description |
|---|---|---|---|
| q | string | Name substring, e.g. "naca 44" or "ag" | |
| family | string | Exact family filter, e.g. "NACA 4-digit" | |
| t_min | number | Min thickness (fraction of chord, e.g. 0.10) | |
| t_max | number | Max thickness | |
| camber_min | number | Min camber (fraction of chord) | |
| camber_max | number | Max camber | |
| limit | integer | Max results (default 25, max 100) |
get_airfoil
Get airfoil · read-only · not metered
Get one airfoil by name: family, source, geometry summary (thickness/camber and their chordwise locations, TE thickness) and CST parameters. Set include_coordinates for Selig-format x,y coordinates — which also returns svg_path and svg_view_box, already scaled 1:1 and y-flipped, so you can draw the section directly instead of deriving a plot from the raw points. Free.
| Input | Type | Required | Description |
|---|---|---|---|
| name | string | yes | Airfoil name, fuzzy-normalized (e.g. "NACA 2412", "ag35") |
| include_coordinates | boolean | Include Selig-ordered [x,y] coordinate array (default false) |
get_polar
Get polar · read-only · not metered
Get stored aerodynamic polars (lift/drag/moment curves) for an airfoil from the foil.tools database. Computed with NeuralFoil, a network trained on XFOIL — near-XFOIL results, not XFOIL runs. Without re_min/re_max it returns a per-Reynolds summary (CLmax, CDmin, max L/D); with either, one curve per Reynolds number as alpha/cl/cd/cm arrays. Ncrit 9 unless ncrit is given (1, 4 and 9 are stored). Free.
| Input | Type | Required | Description |
|---|---|---|---|
| name | string | yes | Airfoil name |
| re_min | number | ||
| re_max | number | ||
| alpha_min | number | Degrees | |
| alpha_max | number | Degrees | |
| cl_min | number | ||
| cl_max | number | ||
| ncrit | number | Transition criterion: 1, 4 or 9 (default 9) |
search_by_operating_point
Search by operating point · read-only · not metered
Rank database airfoils by drag at a single operating point (CL, Re), interpolating each stored polar at the target CL. Returns the lowest-drag candidates with alpha, CD, CM and L/D. Free.
| Input | Type | Required | Description |
|---|---|---|---|
| cl | number | yes | Target lift coefficient |
| re | number | yes | Target Reynolds number |
| re_tol | number | Relative Re tolerance 0–0.5 (default 0.1) | |
| max_cd | number | Discard results with CD above this | |
| alpha_max | number | Only consider polar points below this alpha (degrees) | |
| family | string | Restrict to one airfoil family | |
| limit | integer | Max results (default 20, max 100) |
find_airfoil
Find airfoil for conditions · read-only · not metered
Multi-point airfoil selector: scores every database airfoil against a weighted set of operating points (Re, CL pairs) and returns the top 10, with per-point matched drag/alpha/moment. By default it ranks by drag alone; pass criteria_weights to score a decision matrix on drag, Clmax, stall gentleness, pitching moment, efficiency ratio and L/D placement — each result carries its raw criteria and its 0–1 standing on each, so you can say why it ranked where it did. A point can be marked kind: "constraint" with a load_N instead of a weighted target. For a stabiliser, derive that load from the user's weight and front wing; never assume its size or sign. Balance moments about the front wing's quarter chord: L = (W·x + CM·q·S·c)/arm, + = lift, − = downforce; x = CG aft of it; CM (<0 nose-down), S, c: the front wing's. With no CG given, state x and show ±a few cm. W·x is fixed and CM·q grows with V², so derive each speed; stance aft moves x aft, toward lift. analyze_trim is the full solve. A constraint point is checked against 90% of the stall on its own side (Clmax for positive lift, the negative stall for downforce) and excluded, with why, rather than scored; rejected sections come back in `excluded`. Optional thickness/camber limits, and a CM band (min_cm/max_cm) applied at the scored points. Free.
| Input | Type | Required | Description |
|---|---|---|---|
| points | array of object (re, cl, weight, kind, load_N) | yes | Operating points the design must perform at. |
| ncrit | number | XFOIL transition criterion (default 9) | |
| min_thickness | number | Percent chord, e.g. 10 for 10% | |
| max_thickness | number | Percent chord | |
| min_camber | number | Percent chord | |
| max_camber | number | Percent chord | |
| min_cm | number | Most-negative allowed pitching moment | |
| max_cm | number | ||
| criteria_weights | object (drag, clmax, stall, cm, efficiency, ld_alpha) | Optional decision-matrix weights (after Gudmundsson §8.3.9). Each criterion is scaled 0–1 across the candidates, multiplied by its weight and summed; lowest total ranks first. Omit it, or omit a key, to keep the default {drag: 1, everything else: 0}, which ranks by drag alone exactly as before — so {stall: 3} means "drag 1 and stall 3", not "stall only". Weights are 0–100; at least one must be positive. The textbook preset is {drag: 3, clmax: 2, stall: 3, cm: 1, efficiency: 1, ld_alpha: 1}. |
analyze_airfoil
Analyze airfoil (2D polars) · read-only · not metered
Run NeuralFoil 2D analysis to generate fresh polars (alpha, CL, CD, CM) for an airfoil at given Reynolds numbers. Pass a library airfoil by name, or custom Selig coordinates. Optionally deflect a trailing-edge flap with the `flap` argument — pass the CLEAN section and let the flap argument carry the deflection; sending already-deflected coordinates as well double-counts it. `polars` is ONE flat array with every Reynolds number interleaved, so the returned `chart` block says to group by `Re` before plotting, and names the conventional pairings. Free — rate-limited, not credit-metered.
| Input | Type | Required | Description |
|---|---|---|---|
| name | string | Library airfoil name (alternative to coords) | |
| coords | array of array of number | Custom geometry as Selig-ordered [x,y] pairs (upper TE→LE then lower LE→TE). Alternative to name. | |
| re_values | array of number | Reynolds numbers (default [500000]) | |
| alphas | array of number | Angles of attack in degrees (default -5..15 step 0.5) | |
| ncrit | number | Transition criterion (default 9) | |
| mach | number | Mach number (default 0) | |
| model_size | one of `small`, `medium`, `large` | NeuralFoil model (default large) | |
| flap | object (deflection, hinge_point, symmetric, name) | Optional trailing-edge control surface (flap or aileron). Deflection is DOWNWARDS-POSITIVE: a positive deflection increases lift. Modelled as an equivalent angle-of-attack shift plus a profile-drag multiplier applied to the clean section (AeroSandbox ControlSurface), not by analyzing deflected geometry. Note CM is NOT corrected for deflection and moves the wrong way — treat CL and CD as usable and CM as indicative only. | |
| flap_mode | one of `model`, `geometry` | How to apply the flap. "model" (default) is the AeroSandbox equivalent-alpha model — fast, and exactly identity at zero deflection, but CM is uncorrected. "geometry" actually deflects the section so CM responds, at the cost of a CST refit that smooths the hinge kink. Requires coords or a library name (both resolve to coordinates). |
optimize_airfoil
Optimize airfoil profile · read-only · metered
Shape optimization of an airfoil’s CST parameters (a NeuralFoil population search, then IPOPT gradient refinement) to minimize weighted drag across one or more operating points (Re, CL), with optional geometric constraints. Start from a library airfoil by name or explicit CST parameters. Returns optimized CST parameters, drag improvement and convergence info. Can take up to ~85 seconds. Metered: monthly optimize quota (3/mo free), then 3 credits per run.
| Input | Type | Required | Description |
|---|---|---|---|
| starting_airfoil | string | Library airfoil name to start from (alternative to starting_params) | |
| starting_params | object (upper_weights, lower_weights, leading_edge_weight, TE_thickness) | CST (Kulfan) airfoil parameters. | |
| points | array of object (re, cl, weight, kind, load_N) | yes | Operating points the design must perform at. |
| ncrit | number | Default 9 | |
| mach | number | Default 0 | |
| model_size | one of `small`, `medium`, `large` | Default large | |
| max_iterations | integer | Default 150 | |
| constraints | object (thickness_min, thickness_max, camber_min, camber_max, cm_min, cm_max, te_angle_min_deg, freeze_te_thickness) | Geometric constraints. Thickness/camber are fractions of chord; each *_min must not exceed its *_max. thickness_min/max bound the maximum thickness. A positive camber_min bounds the PEAK camber from below (0.03 to 0.07 = peak camber between 3% and 7%); a camber range that spans zero bounds the whole camber line (-0.02 to 0.06); a band within 0.0025 of zero on both sides is solved as a symmetric section. |
analyze_wing
Analyze wing (3D) · read-only · metered
Analyze a 3D wing (AeroSandbox AeroBuildup strip theory, or VLM) defined by spanwise stations. Returns lift, drag, moments and span efficiency across an alpha sweep or a constant-lift velocity sweep. Your stations are read as control points of a spline, the same wing save_wing_design stores and the wing designer draws, so analysing and saving the same table describe one wing rather than two; the returned `geometry` block says what was analysed, echoing the stations actually solved plus a ready-to-draw planform path. A `chart` block names the x-axis for the sweep that actually ran (alpha, or velocity under constant_lift) and the rows to drop before plotting. Reference area and span are PROJECTED — the wing as seen from above — so they match how a manufacturer quotes a wing rather than the longer measurement along a curved surface; the returned `assumptions` block carries that and the other modelling choices (incompressible, no cavitation or free-surface effect, and a spanwise loading that is always an inviscid VLM solve even on the aerobuildup path). AeroBuildup costs 1 credit; VLM costs 2–3 credits depending on num_spanwise_panels. VLM can take several minutes. Metered: monthly wing-analysis credit quota (10/mo free). Also reports where the wing stalls first — a `stall_progression` block naming the span station and verdict (root-first, mid, tip-first), matched by a spanwise-overlay hint in `chart`.
| Input | Type | Required | Description |
|---|---|---|---|
| stations | array of object (y, le_x, le_z, chord, twist_deg, kulfan) | yes | Spanwise stations root→tip, all lengths in meters. Half-wing only when symmetric. |
| airfoil | string | Convenience: library airfoil name applied to every station instead of per-station kulfan | |
| geometry | one of `cad`, `stations` | How to read `stations`. Default 'cad': as control points of the spline the wing designer draws through them, which is the wing `save_wing_design` stores and `/wing` analyses. 'stations' analyses the table as straight segments between the points — a different, slightly smaller wing. Use it only to reproduce a result from before this default changed. | |
| symmetric | boolean | Mirror about y=0 (default true) | |
| method | one of `aerobuildup`, `vlm` | Default aerobuildup | |
| sweep_mode | one of `alpha`, `constant_lift` | Default alpha | |
| alpha_range | array of number | For alpha sweep: [min, max] degrees (default [-4, 12]) | |
| alpha_step | number | Default 1 | |
| velocity_mps | number | For alpha sweep: freestream velocity (default 15 m/s) | |
| target_lift_N | number | For constant_lift sweep: required lift in Newtons. Negative for a surface that flies at downforce, such as a stabilizer. | |
| velocity_range | array of number | For constant_lift sweep: [vmin, vmax] m/s | |
| velocity_step | number | Default 1 m/s | |
| fluid | object (rho, mu) | Default air {rho: 1.225, mu: 1.81e-5}. Water: {rho: 1000, mu: 1e-3}. | |
| num_spanwise_panels | integer | Default 20. Clamped to 16 by the solver; cost follows the clamped value (≤10 panels = 2 credits, 11–16 = 3). | |
| num_chordwise_panels | integer | Default 8 (VLM only) | |
| neuralfoil_model_size | one of `small`, `medium`, `large` | Default small |
purchase_credits
Buy credits · not read-only · not metered
Create a Stripe Checkout URL to buy a credit pack for the account this session is authenticated as. Return the URL to the user to open in their browser and complete payment. Credits cover the metered tools (optimize_airfoil = 3, analyze_wing = 1–3 by method and panel count) once the monthly free allowance is used up. analyze_airfoil is free and does not spend credits. Packs: starter (50 credits, $10), popular (150 credits, $25), pro (350 credits, $50).
| Input | Type | Required | Description |
|---|---|---|---|
| pack | one of `starter`, `popular`, `pro` | yes | Credit pack to purchase |
search
Search airfoil library · read-only · not metered
Search the foil.tools airfoil library by name, family, or free text and return matching airfoils with their identifiers and links. Pass an identifier from these results to the fetch tool to read the full record for that airfoil. Free.
| Input | Type | Required | Description |
|---|---|---|---|
| query | string | yes | Search terms, e.g. "NACA 4-digit", "ag35", "thick high-lift section" |
fetch
Fetch airfoil record · read-only · not metered
Retrieve the full record for one airfoil by the identifier returned from the search tool: geometry, stored aerodynamic polar summary, and a link to its page on foil.tools. Returns a readable summary, not raw geometry — for CST parameters or Selig x,y coordinates call get_airfoil with include_coordinates instead. Free.
| Input | Type | Required | Description |
|---|---|---|---|
| id | string | yes | Airfoil identifier from a search result, e.g. "NACA 2412" |
save_airfoil
Save airfoil to account · writes to your account · not metered
Save an airfoil to the signed-in foil.tools account so it appears under Dashboard → Foils and can be opened, plotted and exported later. Save when the user asks or agrees to. After optimize_airfoil, offer to save the result rather than saving it unprompted — an optimized profile that is not saved exists only in this conversation. Pass either kulfan CST parameters (preferred, resolution-independent) or a library airfoil name to snapshot. Free; a free account holds 10 saved airfoils.
| Input | Type | Required | Description |
|---|---|---|---|
| name | string | yes | Name to save it under, e.g. "hydrofoil Re500k CL0.6 v2" |
| kulfan | object (upper_weights, lower_weights, leading_edge_weight, TE_thickness) | CST (Kulfan) airfoil parameters. | |
| from_library | string | Alternative to kulfan: snapshot an existing library airfoil by name, e.g. "NACA 2412" | |
| notes | string | Optional short note stored with the airfoil |
save_wing_design
Save wing design to account · writes to your account · not metered
Save a wing design to the signed-in foil.tools account so it appears under Dashboard → Wings and opens in the wing designer. Two ways to give it the wing, and the first is easier: pass `stations` — exactly the array you gave analyze_wing, in metres — and the planform is derived for you. Otherwise pass `design_data.params` directly, which is the designer's own parametric form in MILLIMETRES, where `span` is the HALF-span — but that form is a straight taper, so a curved or elliptical planform only survives via `stations`. Pass `root_foil` too (the same airfoil you gave analyze_wing), or the design opens with no section and no 3D preview. Free; a free account holds 10 saved wing designs.
| Input | Type | Required | Description |
|---|---|---|---|
| name | string | yes | Name to save it under, e.g. "1.5 m glider wing" |
| stations | array of object (y, le_x, le_z, chord, twist_deg) | Preferred. The same spanwise stations you passed to analyze_wing, root→tip, in METRES. The planform is derived from these, so you do not convert units or work out half-span yourself, and every station is kept — pass all of them, not just root and tip, or the saved wing is a straight taper between the two. Only valid for a symmetric half-wing, the analyze_wing default. | |
| symmetric | boolean | Whether `stations` describe a symmetric half-wing. Default true; false is rejected. | |
| root_foil | string | Airfoil at the root, e.g. "goe617" — normally the same section you gave analyze_wing. Fuzzy-matched on case, spaces and dashes. Without it the saved design has no section and the designer opens it with an empty 3D preview. | |
| tip_foil | string | Airfoil at the tip, if it differs from root_foil. Omit for a single-section wing. | |
| design_data | object (params, rootFoilName, tipFoilName, teThicknessMm) | The parametric planform the wing designer reads. Lengths in millimetres. Only `params` is required; the designer fills in sensible curves for anything omitted. | |
| notes | string | Optional short note stored with the design |
save_wing_analysis
Save wing analysis to account · writes to your account · not metered
Save the results of an analyze_wing run to the signed-in foil.tools account, so it appears under Dashboard → Wing Analyses. Save when the user asks or agrees to. For a run they may want to compare against later, offer to save it rather than saving it unprompted — a VLM sweep costs credits and takes minutes to reproduce. Link it to a saved design by passing wing_design_id from save_wing_design. Free; a free account holds 10 saved analyses.
| Input | Type | Required | Description |
|---|---|---|---|
| name | string | yes | Name to save it under, e.g. "1.5 m glider — VLM, 16 panels" |
| analysis_data | object | yes | The result returned by analyze_wing, passed through unchanged. |
| wing_design_id | string | Optional id from save_wing_design, to link the analysis to its design |
list_saved_airfoils
List saved airfoils · reads your account · not metered
List the airfoils saved on the signed-in foil.tools account (Dashboard → Foils), newest first. This is how you find out what the user already has — a section optimized in an earlier conversation is invisible to you until you look. Returns summaries only (id, name, type, notes, dates), not geometry, so it is cheap to call up front; pass an id to get_saved_airfoil for the CST parameters. Only ever returns this account's own rows. Free.
| Input | Type | Required | Description |
|---|---|---|---|
| limit | integer | Max rows to return, newest first (default 20, max 50). |
get_saved_airfoil
Get saved airfoil · reads your account · not metered
Get one airfoil saved on the signed-in account by its id, with the geometry it was stored with — CST parameters for a kulfan foil, coordinates for a dat one. The parameters come back in the shape analyze_airfoil and save_wing_design accept, so a section optimized weeks ago can be re-analyzed or reused without recomputing it. Ids come from list_saved_airfoils. This reads the user's own saved work; for a library section use get_airfoil instead. Free.
| Input | Type | Required | Description |
|---|---|---|---|
| id | string | yes | Row id from list_saved_airfoils or save_airfoil |
list_wing_designs
List saved wing designs · reads your account · not metered
List the wing designs saved on the signed-in foil.tools account (Dashboard → Wings), newest first. Call this before designing a wing the user may already have, and to recover a design id — save_wing_analysis links an analysis to a design by that id, and without this tool the id was only obtainable in the same conversation that created it. Each row carries the planform parameters (millimetres; `span` is the HALF-span) so you can describe the wing without fetching it, plus detail_bytes so you can see what get_wing_design would cost. Only ever returns this account's own rows. Free.
| Input | Type | Required | Description |
|---|---|---|---|
| limit | integer | Max rows to return, newest first (default 20, max 50). |
get_wing_design
Get saved wing design · reads your account · not metered
Get one wing design saved on the signed-in account by its id, as the full designer document — the parametric planform plus the spline channels that carry a curved or elliptical shape. This is how you reopen a wing from an earlier conversation instead of asking the user to describe it again. Ids come from list_wing_designs. Lengths are in MILLIMETRES and `span` is the HALF-span, which is not what analyze_wing takes — the response repeats that. Free.
| Input | Type | Required | Description |
|---|---|---|---|
| id | string | yes | Row id from list_wing_designs or save_wing_design |
list_wing_analyses
List saved wing analyses · reads your account · not metered
List the wing analyses saved on the signed-in foil.tools account (Dashboard → Wing Analyses), newest first. Worth checking before running analyze_wing: a VLM sweep costs credits and takes minutes, and the user may already have paid for the answer. Pass wing_design_id to see only the runs attached to one design. Each row carries method_used and detail_bytes, not the results — call get_wing_analysis for those. Only ever returns this account's own rows. Free.
| Input | Type | Required | Description |
|---|---|---|---|
| wing_design_id | string | Optional: only analyses linked to this saved design (id from list_wing_designs) | |
| limit | integer | Max rows to return, newest first (default 20, max 50). |
get_wing_analysis
Get saved wing analysis · reads your account · not metered
Get one wing analysis saved on the signed-in account by its id, with the full stored results — the polar, the spanwise loading, whatever the run produced. Use it to compare a new run against an old one, or to answer a question about a wing the user analyzed weeks ago without paying for the sweep again. Ids and payload sizes come from list_wing_analyses; a large run can be tens of kilobytes, so check detail_bytes there first. Free.
| Input | Type | Required | Description |
|---|---|---|---|
| id | string | yes | Row id from list_wing_analyses or save_wing_analysis |
analyze_trim
Trim an aircraft (multi-surface) · reads your account · metered
Trim an aircraft: a wing plus a stabiliser (and any further surfaces) about a CG, solved together on AeroSandbox LiftingLine so the stabiliser flies in the wing's downwash. Returns the trim angle of attack, the stabiliser setting that balances the moment (or, with free: "cg", the CG station for a fixed setting), the lift and drag on every surface, the required thrust from the x-balance, and the static margin — at one speed (velocity_mps) or across a range (velocity_range + velocity_step, up to 20 rows). Surfaces come from saved wing designs (design_id, from list_wing_designs) or station tables; the CG has x AND z because the height of a hydrofoil rider is first order; masts and boards enter as drag_elements. Every row reports its residuals; a speed the craft cannot fly is refused with a reason, never trimmed silently. The free closed-form estimate for the same geometry comes back beside the answer. PAID-ONLY: 2 credits for a trim point, 3 credits for a sweep, no free allowance (unlimited on Pro); sign-in required. A sweep in which some rows are refused is charged; one in which every row is refused is not.
| Input | Type | Required | Description |
|---|---|---|---|
| surfaces | array of object (name, design_id, stations, airfoil, symmetric, incidence_deg, x, z) | yes | The first entry is the main wing and the reference surface. |
| cg | object (x, z) | yes | Centre of gravity in the craft frame, metres: x (+aft) AND z (+up). Moments are taken about it. |
| weight_N | number | yes | The load the assembly must carry (N) — all-up mass × 9.81. |
| fluid | object (rho, mu) | Defaults to air. Sea water: rho 1025, mu 0.00108. | |
| velocity_mps | number | One speed (m/s) — a trim point, 2 credits. | |
| velocity_range | array of number | [v_min, v_max] m/s — a sweep, 3 credits. | |
| velocity_step | number | Sweep step (m/s). Default: a twelfth of the range. | |
| free | one of `incidence`, `cg` | What is solved for besides alpha: the trim surface's incidence (default) or the CG x station. | |
| trim_surface | string | Name of the surface whose incidence is free. Default: the second surface. | |
| thrust_line_z | number | z of the thrust line (m, +up). Default: through the CG (no thrust moment). | |
| drag_elements | array of object (name, kind, x, z, chord, length, kulfan, CD_A) | Masts, fuselages, boards: non-lifting drag with a z-arm. | |
| spanwise_resolution | integer | LiftingLine strips per station interval, 1–4. Default 2. |