TheFaceAnalysis

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

Read-only status is already covered by readOnlyHint, but the description adds important behavior: the seven-rule classifier, the exact return contents, the unit flexibility, the flipping behavior on borderline faces, and the lack of any accuracy claim. These are real behavioral traits beyond the annotations and are highly useful for trust calibration.

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?

Four sentences, each earning its place: what it does, what it returns, what it is not, and the accuracy caveat. The information is front-loaded and there is no filler.

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 read-only, four-parameter computation tool with full schema coverage and no output schema, the description covers inputs, outputs, limitations, unit handling, and the photo alternative. Nothing essential for correct invocation 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 all four parameters are fully documented. The description adds only unit flexibility ('any consistent unit') and reinforces that the inputs are distances. That is useful but the schema already carries the semantics, so the baseline of 3 fits.

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 states a specific verb (classify) and resource (face shape), names the exact inputs (four distances) and outputs (shape, matched rule, four ratios), and distinguishes itself from its siblings by naming get_embed_snippet and the site for photo-measurement. An agent can see immediately what this does and what it does not.

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 clearly says when to use this tool: when you already have four distances. It rules out photos and points to get_embed_snippet or the site. There is no explicit exclusion against other computation tools, but the input requirement is a strong and clear usage condition.

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 establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: the license is CC BY 4.0 and, importantly, that this applies to the aggregate numbers, plus the fact that the source photo set is included — licensing scope the agent would otherwise have to assume.

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?

One compact sentence covering the return payload followed by a short usage trigger; no filler. The mixed return-list / usage-instruction structure is slightly compressed but still front-loaded and readable.

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?

With no output schema and no parameters, the description is the only source for return values, and it does enumerate them (citation text, license, source photo set). What is missing is minor: no note on whether non-aggregate figures carry different licensing, and no routing to sibling tools.

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?

The tool takes no parameters, so there is nothing for the description to disambiguate; the baseline for a zero-parameter tool is 4. The empty schema is consistent with the description, which describes a fixed-content retrieval.

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 names the concrete payload (citation text, license terms, source photo set) for a clearly named retrieval tool, so an agent knows what comes back. It is a content list rather than a verb+resource statement, and it does not explicitly distinguish itself from nearby informational siblings like get_methodology or get_reference_statistics.

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 when quoting a number" gives one concrete trigger condition, which is better than nothing. However, it names no alternative and gives no exclusion (e.g., what to use instead when you need the methodology behind a number), leaving sibling selection to inference.

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=true and openWorldHint=false, and the description adds real behavioral context beyond them: the widget runs client-side ('measures the visitor's photo in their browser'), requires 'no sign-up', and embeds a mandatory visible credit link. Those details affect how an agent presents and explains the snippet. It stops short of 5 since nothing about permissions, rate limits, or delivery format is stated.

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?

A single front-loaded sentence that leads with the artifact before the parenthetical clarifications; nothing is redundant. The nested parentheses make it slightly dense but no sentence 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?

With no output schema, the description carries the return-value burden and does describe what the snippet contains (embed HTML plus a visible credit link). The only untouched element is the 'size' parameter, which the schema fully covers, so an agent has nearly everything needed to call and explain this tool.

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% and the single enum parameter 'size' already documents its three values with pixel widths. The description never mentions size, so it adds nothing beyond the schema, making the baseline 3 correct.

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 precisely names the artifact returned (pasteable HTML for the face shape finder) and its function, which is distinct from every sibling (citations, face-type lookups, statistics). The verb is implicit rather than stated ('get'/'return'), so it falls just short of the crisp verb+resource pattern.

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 implies the audience and use case ('a website owner can paste to add the free face shape finder'), which signals when this tool is relevant. However, it gives no explicit when-to-use vs alternatives guidance or exclusions relative to siblings like get_citation or get_methodology.

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=true and openWorldHint=false, so the safe, closed-world lookup profile is covered. The description adds content-level transparency (it returns the definition, the exact threshold rule, and a page URL), which is meaningful without an output schema, but says nothing about invalid category/slug handling or lookup failures.

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?

Two sentences, zero filler: the first front-loads the returned payload (definition, threshold rule, URL) and the second supplies a concrete example. Nothing is wasted or buried.

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?

With no output schema, the description correctly carries the return-value burden by naming the three things returned, which is complete enough for a simple two-parameter lookup. The only gap is error/edge-case behavior for unrecognized categories or slugs.

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 only 50% — the slug property carries examples while the category enum has no prose. The description compensates by demonstrating a valid pairing (category 'face', slug 'oval'), clarifying that both are identifiers rather than free text, though it adds no detail on slug formatting or invalid-value behavior.

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 (retrieve/describe) and resource (one face/eye/lip/nose type), and enumerates the exact payload: definition, measurement rule from a front photo, and page URL. It is clearly distinguishable from the plural sibling list_face_types by virtue of fetching a single item, though it never names that 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?

The description implies usage — look up one type by category+slug to get its definition and threshold rule — via the worked example, but it offers no explicit when-to-use guidance or exclusions relative to list_face_types, classify_face_shape, or get_reference_statistics. Usage must be inferred from the tool name and payload.

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=true and openWorldHint=false, so the safety profile is covered without the description's help. The description does add value by disclosing the exact inventory of the returned documentation (including the candid note that the 1-10 score did not predict human ratings), but with no output schema this return-shape context is present yet not fully specified.

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?

One sentence, front-loaded with the framing 'How the numbers are made', then a tight colon-delimited inventory. The parenthetical about failing to predict human raters is short and genuinely informative rather than filler.

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 one-optional-parameter documentation tool with no output schema, the description is nearly sufficient: it enumerates what comes back and covers the changelog toggle. Only the return format/media (structured text vs. object) is left unstated, a minor 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 100% and the single optional parameter include_changelog is fully described in the schema as returning the dated change history. The description's 'Includes the method change history' mirrors that same contract without adding format, size, or default guidance, so the baseline 3 applies.

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 names the resource precisely and enumerates its contents (landmark model, classification thresholds, 1-10 score construction, rater correlation, change history), so an agent knows exactly what payload it gets. It does not explicitly differentiate itself from siblings like get_reference_statistics or get_citation, which keeps it out of 5 territory.

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?

There is no when-to-use or when-not-to-use guidance and no alternative sibling is named. An agent must infer from the tool name alone that this is the documentation/definitions lookup, which is implied usage rather than stated 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 cover the safety profile (readOnlyHint=true, openWorldHint=false), so the description's job is to add context — and it does: dataset provenance (102 faces, 49 women/53 men, one city), the measurement pipeline (478-point MediaPipe), and an explicit limitation that these describe a specific research set, not a population. It also names the returned percentile set, which compensates for the absent output schema.

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?

Three dense sentences that are front-loaded with the substantive content (what is measured) before the scope caveat. The measure list is long but each item earns its place; nothing is padding.

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 read-only reference-statistics tool with full schema coverage and no output schema, the description supplies the data provenance, the returned statistics, and the generalizability caveat an agent needs. Only a note on how results are structured per group/measure combination is arguably missing, which is minor.

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 real value by expanding the cryptic enum keys into human terms (fwhr → fWHR, pd → pupillary distance, tilt → canthal tilt) and restating the group breakdown. This goes beyond what the raw enum lists convey.

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: percentile statistics of facial measurements from a named dataset, with the exact measures enumerated. It is clearly distinguishable from classify_face_shape or get_face_type by being a static reference table, though it never explicitly names a sibling or its contrast with them.

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?

Usage is only implied: an agent can infer this is the lookup for population-reference percentiles to compare a face against. There is no explicit when-to-use, no statement of when NOT to use it versus the classification siblings, though the closing caveat about generalizability does guide interpretation.

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 establish this as a read-only, non-open-world call, so the safety profile is covered. The description adds genuinely useful context beyond that: the coverage is measured against exactly 102 reference faces, and — critically — the split reflects how the detector partitions those faces rather than population prevalence, which prevents a common misreading of the 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?

Two sentences, no filler. The output shape is front-loaded and the interpretive caveat follows, which is the right order for an agent that first needs to know what it gets and then how to read 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?

With no output schema, the description usefully names the four returned fields and the 102-face reference basis, so an agent knows what comes back. The omission of any routing guidance against the sibling lookup tools is the only meaningful 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 100% with a single enum-typed category parameter whose omission behavior is documented in the schema itself. The description does not restate or enrich the parameter (it references the four categories only obliquely), so the baseline 3 for schema-carried semantics applies.

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 gives a specific verb and resource ("Lists the types the site's detectors use") and enumerates the returned fields (slug, name, page URL, coverage count). It is clearly distinct from the singular get_face_type by implication, but never explicitly contrasts itself with siblings such as get_face_type or get_reference_statistics.

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?

There is no statement of when to choose this tool over get_face_type or get_reference_statistics, and no exclusions or prerequisites. The second sentence is an interpretation caveat about the returned data, not guidance on tool selection, so the agent is left to infer the routing.

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