Tool reference
Seven read-only tools. This page is generated at build time from the published thefaceanalysis-mcp@0.1.0 package: the parameters come from the server's own tools/list and the responses from calling each tool, so it cannot drift from the server.
isError: true and a message that lists the valid options.get_reference_statistics
Percentiles (p10, p25, median, p75, p90, min, max) of facial measurements from 102 adult faces (49 women, 53 men) of the Face Research Lab London Set, measured with a 478-point MediaPipe landmarker. Measures: composite score, symmetry, golden ratio fit, fWHR, midface ratio, pupillary distance, canthal tilt. Aggregates only; one research set photographed in one city, so these describe these faces, not a population.
| Parameter | Type | Required | Description |
|---|---|---|---|
measure | enum: composite, symmetry, golden, fwhr, midface, pd, tilt | no | One measure. Omit for all. |
group | enum: all, female, male | no | all, female or male. Omit for all three. |
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_reference_statistics",
"arguments": {
"measure": "fwhr",
"group": "all"
}
}
}{
"n": 102,
"measuredOn": "2026-10-06",
"statistics": {
"fwhr": {
"unit": "ratio",
"all": {
"n": 102,
"p10": 1.64,
"p25": 1.72,
"median": 1.78,
"p75": 1.86,
"p90": 1.95,
"min": 1.54,
"max": 2.1
}
}
},
"citeAs": "The Face Analysis (2026). Face Measurement Statistics 2026: 102 faces measured with MediaPipe. Updated 6 October 2026.",
"license": {
"name": "CC BY 4.0",
"url": "https://creativecommons.org/licenses/by/4.0/"
},
"page": "https://thefaceanalysis.com/face-measurement-statistics"
}list_face_types
Lists the types the site's detectors use, with slug, name, page URL and how many of the 102 reference faces each type covered. The split shows how the detector divides these faces, not how common a type is in a population.
| Parameter | Type | Required | Description |
|---|---|---|---|
category | enum: face, eye, lip, nose | no | Omit for all four categories. |
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_face_types",
"arguments": {
"category": "face"
}
}
}{
"face": {
"hub": "https://thefaceanalysis.com/face-shape",
"types": [
{
"slug": "diamond",
"name": "Diamond",
"page": "https://thefaceanalysis.com/face-shape/diamond",
"referenceCount": 9,
"referenceShare": 0.088
},
{
"slug": "oval",
"name": "Oval",
"page": "https://thefaceanalysis.com/face-shape/oval",
"referenceCount": 38,
"referenceShare": 0.373
},
{
"slug": "round",
"name": "Round",
"page": "https://thefaceanalysis.com/face-shape/round",
"referenceCount": 13,
"referenceShare": 0.127
},
{
"slug": "heart",
"name": "Heart",
"page": "https://thefaceanalysis.com/face-shape/heart",
"referenceCount": 12,
"referenceShare": 0.118
},
{
"slug": "square",
"name": "Square",
"page": "https://thefaceanalysis.com/face-shape/square",
"referenceCount": 10,
"referenceShare": 0.098
},
{
"slug": "oblong",
"name": "Oblong",
"page": "https://thefaceanalysis.com/face-shape/oblong",
"referenceCount": 10,
"referenceShare": 0.098
},
{
"slug": "triangle",
"name": "Triangle",
"page": "https://thefaceanalysis.com/face-shape/triangle",
"referenceCount": 10,
"referenceShare": 0.098
}
]
}
}get_face_type
Definition and how the type is measured from a front photo (the exact threshold rule), plus its page URL. Example: category 'face', slug 'oval'.
| Parameter | Type | Required | Description |
|---|---|---|---|
category | enum: face, eye, lip, nose | yes | |
slug | string | yes | e.g. oval, heart, hooded, upturned |
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_face_type",
"arguments": {
"category": "face",
"slug": "oval"
}
}
}{
"slug": "oval",
"name": "Oval",
"page": "https://thefaceanalysis.com/face-shape/oval",
"definition": "An oval face is longer than it is wide, with a jaw that curves rather than corners. It is the most commonly assigned shape, partly because it is genuinely frequent and partly because it is where borderline measurements land.",
"howMeasured": "Oval is the shape that remains when none of the six narrower conditions holds: the face is not long enough to be oblong (length under 1.23 times cheekbone width), the jaw tapers enough not to read round, square or triangle, and the forehead and jaw are too balanced for heart or diamond. That makes it a balanced proportion rather than a single threshold, and the most common result. Charts that quote 1.5 or 1.6 measure length from the hairline, which a photo landmark cannot see; this test measures from the top of the forehead, so its numbers run lower and its cut points are calibrated to its own measurements.",
"referenceCount": 38,
"referenceShare": 0.373
}classify_face_shape
Runs the same seven-rule face shape classifier as thefaceanalysis.com/face-shape-detector on four distances (any consistent unit: pixels, mm or landmark units). Returns the shape, the rule that matched and the four ratios. It does not look at photos: to measure a photo, use the widget (get_embed_snippet) or the site. Borderline faces can flip between two shapes; no accuracy figure is claimed because the reference set has no labelled face types.
| Parameter | Type | Required | Description |
|---|---|---|---|
face_length | number | yes | Top of the forehead surface to the bottom of the chin |
cheekbone_width | number | yes | Widest point across the cheekbones |
forehead_width | number | yes | Width across the temples |
jaw_width | number | yes | Width across the jaw |
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "classify_face_shape",
"arguments": {
"face_length": 1.3,
"cheekbone_width": 1,
"forehead_width": 0.9,
"jaw_width": 0.8
}
}
}{
"shape": "oblong",
"matchedRule": "length ÷ cheekbone width ≥ 1.229",
"ratios": {
"lengthToCheekbone": 1.3,
"jawToCheekbone": 0.8,
"foreheadToCheekbone": 0.9,
"foreheadToJaw": 1.125
},
"method": "https://thefaceanalysis.com/methodology",
"detector": "https://thefaceanalysis.com/face-shape-detector"
}get_methodology
How the numbers are made: the landmark model, every classification threshold, how the 1-10 score is built, and how it correlated with 2,513 human raters on the same faces (it did not predict them). Includes the method change history.
| Parameter | Type | Required | Description |
|---|---|---|---|
include_changelog | boolean | no | Also return the dated change history. |
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_methodology",
"arguments": {}
}
}The response is large. Its top-level keys are methodology, engine, score, thresholds, validity, notes; the thresholds and validity blocks are the same ones documented on the dataset page.
get_citation
Citation text, license (CC BY 4.0 for the aggregate numbers) and the source photo set. Use when quoting a number.
No parameters.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_citation",
"arguments": {}
}
}{
"citeAs": "The Face Analysis (2026). Face Measurement Statistics 2026: 102 faces measured with MediaPipe. Updated 6 October 2026.",
"page": "https://thefaceanalysis.com/face-measurement-statistics",
"license": {
"name": "CC BY 4.0",
"url": "https://creativecommons.org/licenses/by/4.0/"
},
"source": {
"name": "Face Research Lab London Set",
"citation": "DeBruine, L. & Jones, B. (2017). Face Research Lab London Set. figshare. doi:10.6084/m9.figshare.5047666.v5 (CC BY 4.0).",
"doi": "https://doi.org/10.6084/m9.figshare.5047666.v5",
"license": "CC BY 4.0"
},
"downloads": {
"json": "https://thefaceanalysis.com/data/reference-set.json",
"csv": "https://thefaceanalysis.com/data/face-measurements.csv",
"types": "https://thefaceanalysis.com/data/types.json"
}
}get_embed_snippet
HTML a website owner can paste to add the free face shape finder (it measures the visitor's photo in their browser, no sign-up). Includes the visible credit link the terms ask for.
| Parameter | Type | Required | Description |
|---|---|---|---|
size | enum: compact, standard, wide | no | compact 360px, standard 480px, wide 720px |
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_embed_snippet",
"arguments": {
"size": "wide"
}
}
}{
"snippet": "<div data-tfa-widget=\"face-shape\" data-size=\"wide\"></div>\n<script async src=\"https://thefaceanalysis.com/embed.js\"></script>",
"terms": "Free to use, including commercially. Keep the credit link visible. Do not present the reading as a medical or cosmetic diagnosis.",
"page": "https://thefaceanalysis.com/embed"
}