Eligibility
This chapter defines what is allowed to be part of a gradable schema. Eligibility is the upstream gate: an endpoint that is not eligible MUST NOT appear in a schema, and the chapter sets out the exclusion criteria, the access classes, the schema-splitting rule, and the target-audience priority. The maximalism principle in 01-default-journey.md operates inside this eligibility boundary — “all admitted endpoints” means “all endpoints that pass the rules in this chapter”.
Read Focus
Section titled “Read Focus”The core focus of a FlowMCP schema is reading data. Write, update, and delete operations are not categorically forbidden, but they SHOULD NOT appear in a schema.
- Graders MUST NOT execute state-changing calls during grading. All grader-driven test invocations MUST be read-only.
- Schema authors SHOULD restrict the schema surface to read endpoints.
A schema that contains write/update/delete tools without an explicit, documented justification will be flagged under Exclusion Criteria below.
Exclusion Criteria
Section titled “Exclusion Criteria”The following endpoints MUST NOT be included in a gradable schema:
- Legally non-public endpoints — endpoints that, by law or by the provider’s published terms, are not permitted for public use.
- Non-general endpoints — customer- or tenant-specific administration APIs (e.g. account-management endpoints scoped to a single tenant).
- Write/update/delete endpoints without justification — write operations that lack a specific, documented reason for inclusion.
- Reachable but undocumented endpoints — endpoints that are publicly reachable but not actually documented. These MAY indicate a provider-side defect (an endpoint that was unintentionally exposed) and MUST NOT be included on the assumption that “reachable = public-intent”.
- Private runtime schemas (
requires-private-data) — schemas that require private, local-only, or otherwise non-public data and are invoked ad-hoc by path (never registered in a sharedschemaFolders[]catalog). Being unregistered, they are structurally outside the discoverable corpus; being non-public, they are outside the graded corpus.
The undocumented-endpoint exclusion is a distinct, named exclusion ground. Reachability is not documentation.
Public-only Grading Corpus
Section titled “Public-only Grading Corpus”Grading operates on the public corpus only. A schema marked requires-private-data — one that depends on private or local-only data and is reached through a private ad-hoc call rather than through a registered catalog — is out of grading scope by definition:
- It never appears in the shared catalog, so it is not enumerable by a grader.
- Its data is not publicly reachable, so a grader cannot reproduce a call.
- Excluding it is not a quality judgement; the schema is simply outside the public target audience this chapter grades against.
Graders MUST NOT attempt to score a requires-private-data schema, and a corpus report MUST NOT count it as an ungraded public schema.
Empty-Context Convention
Section titled “Empty-Context Convention”A grading is performed in an empty LLM context (/clear before start). This
obligation is conventional — it is not machine-checked, but is ensured
through the entry-point prompt (see 20-entry-point-prompt.md)
and the responsibility of the grader. By starting the prompt, the grader confirms
that no relevant prior context from earlier sessions is present.
Rationale: pre-loading the context (e.g. through prior research on the domain)
systematically biases the persona evaluation upward. Empty context is the
operational precondition for the persona Lens (see
12-personas-contract.md) to evaluate genuinely
from the assigned persona rather than from the prior knowledge of the grader LLM.
| Aspect | Value |
|---|---|
| Obligation type | Convention (organisational, not technical) |
| Anchoring | Entry-point prompt in the grading repository (20-entry-point-prompt.md) |
| Checkable? | No — trust-based |
| Consequence of violation | Evaluation drift (the persona Lens escapes into the LLM’s prior knowledge) |
Reference: 20-entry-point-prompt.md (entry-point prompt template).
Access Classes
Section titled “Access Classes”A schema’s endpoints fall into one of three access classes:
| Class | Status | Conditions |
|---|---|---|
| Free, no API key | Permitted | Endpoint is callable without any credential. |
| API key (static) | Permitted | API key is passed at runtime start as a static parameter (e.g. requiredServerParams). |
| Commercial with free tier | Permitted | At least a partial free tier exists; otherwise the endpoint is treated as non-eligible. |
OAuth Access
Section titled “OAuth Access”OAuth-based access is out of scope. Endpoints whose only access path is OAuth (interactive consent flow, user-bound tokens) MUST NOT be part of a gradable schema. This is a hard exclusion, not a soft “currently unsupported” — implementers MUST treat it as MUST NOT per BCP 14.
OAuth support MAY be introduced in a later spec version. Until then, no exception.
Schema Splitting
Section titled “Schema Splitting”If a single API exposes both freely accessible and API-key-only endpoints, the freely accessible endpoints and the API-key-only endpoints MUST be split into separate schemas. The binding rules:
| Rule | Level |
|---|---|
| Free and API-key-only endpoints are split into separate schemas | MUST |
| One schema mixes free and API-key-only endpoints | MUST NOT |
| The split is reflected in the schema metadata (distinct namespaces or distinct schema files) | MUST |
Both schemas — the free schema and the API-key schema — are individually maximalist under 01-default-journey.md | MUST |
The split is independent of the maximalism principle. The reason for it is twofold: it lets the free schema be used without credentials, and it lets the grader run the free schema fully autonomously while gating the API-key schema on credential availability.
Target Audience for Data Sources
Section titled “Target Audience for Data Sources”The primary target audience for FlowMCP data sources is public interfaces:
- Public-sector authorities.
- Public institutions (universities, statistical offices, regulators).
- Private parties offering public data (open-data publishers).
The secondary target audience is commercial providers with a free tier.
Selection of data sources SHOULD reflect this priority order. Commercial APIs without a free tier do not belong in the FlowMCP corpus.
Verification
Section titled “Verification”The eligibility rules of Exclusion Criteria–Target Audience for Data Sources are verified during the grading areas defined in 04-phases-single.md:
- Exclusion Criteria is enforced before the
single-testarea runs — the endpoint list MUST already be eligibility-classified. - Access Classes and Schema Splitting are reflected in the
single-testandtools-aggregate-schemaareas. - Target Audience for Data Sources is a corpus-level guideline — verified by the maintainers, not by an automated grader.
The detailed verification method belongs to the grader implementation and is out of scope for this chapter.
Related
Section titled “Related”- ./00-overview.md — see chapter 00.
- ./01-default-journey.md — see chapter 01.
- ./04-phases-single.md — see chapter 04.
- ./20-entry-point-prompt.md — see chapter 20.