US ultramarathons: dates, places, distances, elevation, prices. Every value cited.
Scored across 8 tools
Each tool has a distinct role: schema inspection, race search, race detail retrieval, arbitrary SQL querying, source reading, single-field correction, new-race proposal, and structural problem reporting. The only surface overlap is search_races vs. query and get_race vs. query, but the descriptions clearly separate convenience search from custom SQL and single-race detail from general querying.
Six of eight tools follow a clear verb_noun pattern: get_race, propose_correction, propose_race, read_source, report_problem, search_races. The bare verbs describe and query are minor deviations, but the overall convention remains readable and predictable.
Eight tools are well scoped for a cited ultramarathon index. Each tool covers a meaningful operation: metadata, search, detail, SQL access, source reading, corrections, additions, and problem reporting.
The surface covers the full read/propose workflow: discover schema, search races, inspect one race with editions and citations, run custom SQL, read source pages, propose corrections, propose new races, and report structural problems. No obvious lifecycle gap remains for the stated domain.
What Ultrapedia holds: the queryable views, every column and what it means,
the allowed values of category columns, and how many races there are. Read this
before writing SQL for query.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, closed-world, so safety needs no restatement. The description adds useful context about the nature of the payload (a schema/metadata dump, including cardinality), though it does not say how large the response is or whether output is formatted for direct SQL authoring.
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, content-first: what is inside, then when to call it. Every clause earns its place with 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?
A no-parameter, annotated, read-only tool with an output schema; the description covers what the agent needs (content scope and sequencing before `query`) without duplicating return-value documentation.
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?
Zero parameters, so the schema baseline applies; the description correctly implies the call is argument-free. Nothing further is needed on parameter semantics.
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 enumerates exactly what the tool returns: queryable views, columns and meanings, allowed category values, and race counts. It is clearly distinguishable from the sibling `query`, which executes SQL rather than documenting it.
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 tells the agent when to call it: "Read this before writing SQL for `query`," naming the sibling and the precondition. No inference required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Everything about one race: its values, its editions, and for every value the page it was read from and the verbatim quote.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real value by disclosing provenance output (page + verbatim quote), but says nothing about missing-slug errors or response size.
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 enumerates the returned contents with zero filler. Every clause earns its place.
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?
No output schema exists, so the description usefully explains the return shape including provenance, which is the tool's distinguishing feature. It falls short only on the required slug's semantics and domain terms like 'values' and 'editions'.
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 0% and the description never mentions the 'slug' parameter at all — no format, no origin (presumably from search_races), no case/normalization expectations. With only one parameter carrying the entire input burden, this is a meaningful gap.
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 ('get one race') and enumerates the payload (values, editions, source page, verbatim quote). The singular 'one race' implicitly contrasts with search_races, though no sibling is named.
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 detail-fetch counterpart to search_races, but the description never says when to use this versus searching, nor what the slug must come from.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a value for one field of one race, read from a web page — a correction
or a value the index is missing. field is a column name from describe;
value is in that column's form and units (gain_m in metres, dates yyyy-mm-dd,
start_time HH:MM 24h, price_usd a number). quote must be copied verbatim from
source_url and must show the value. For date, start time, price, aid stations,
drop bags and runners, year is the edition year. The server checks the
quote on the page; the result says whether the value was applied, held for a
maintainer, or rejected and why.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| year | No | ||
| field | Yes | ||
| quote | Yes | ||
| value | Yes | ||
| source_url | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say it is a non-idempotent, open-world write; the description adds the critical behavior that the server verifies the quote against the live page and returns a tri-state outcome (applied, held for a maintainer, or rejected with a reason). That outcome model is non-obvious and would change how an agent retries or reports, and it is not derivable from any structured field.
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 action and scope in the first clause, then moves through field/value/quote semantics to the outcome, one idea per sentence. No filler and no restatement of the tool name.
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?
No output schema exists, yet the description supplies the return semantics (applied / held / rejected with reason), the unit conventions for `value`, the year conditionality, and the source-verification requirement. An agent has enough to call it correctly and interpret the answer without guessing.
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 0%, so the description must carry every parameter, and it does: field as a column name from `describe`, value with per-column forms and units (gain_m in metres, dates yyyy-mm-dd, start_time HH:MM 24h, price_usd numeric), quote as verbatim source text that must display the value, and the conditional meaning of year.
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 ('send a value'), a tightly bounded resource ('one field of one race'), and the purpose (correction or a value the index is missing). 'One field of one race' cleanly separates it from propose_race, which would create a whole race entry rather than patch a single column.
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 preconditions: `field` must come from `describe`, `quote` must be copied verbatim from `source_url` and must show the value, and `year` is the edition year for date/start time/price/aid stations/drop bags/runners. It does not explicitly say when to prefer this over report_problem for a data problem, so the routing is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a US ultramarathon the index does not have yet. Check with search_races
first. quote is copied verbatim from source_url and names the race. One call
for each distance (a 50K and a 100M at the same event are two races).
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | ||
| name | Yes | ||
| quote | Yes | ||
| state | No | ||
| source_url | Yes | ||
| website_url | No | ||
| distance_category | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true and idempotentHint=false, so the submission/mutating nature is covered. The description usefully adds that one call is needed per distance and that `quote` is a verbatim copy from `source_url`, but it never says what happens after submission (moderation queue, duplicate rejection, review latency) — meaningful for a proposal tool.
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 short sentences, front-loaded with the admission criterion and the prerequisite check before the parameter details. No filler; each sentence conveys a distinct constraint. Slightly telegraphic phrasing ('Send a US ultramarathon the index does not have yet') costs a bit of clarity.
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 7 parameters, no output schema, and 0% schema coverage, the description covers the two non-obvious fields and the multiplicity rule but leaves the remaining parameters and the post-submission outcome undocumented. Adequate to attempt a call, but not fully sufficient for an agent to predict what a successful submission yields.
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 0% across 7 parameters, so the description carries the burden. It explains `quote` well (verbatim from `source_url`, names the race) and clarifies `distance_category` through the one-race-per-distance rule, plus the US-only scope affecting city/state. But `name`, `city`, `state`, and `website_url` receive no semantic elaboration beyond their self-evident titles.
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 ('Send a US ultramarathon the index does not have yet'), which pins both the action and the admission criterion of novelty. It implicitly separates itself from search_races (already-indexed races) and from propose_correction (fixes to existing entries), though the latter is never named 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?
'Check with search_races first' is an explicit precondition naming the sibling to consult before calling. 'One call for each distance' gives concrete guidance on call granularity. It stops short of saying when-not to use it (e.g. use propose_correction for errors in an existing entry), so the exclusion side is inferred rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run one read-only SQL SELECT (SQLite) over the views races, editions and
sources. Returns columns and rows; truncated is true when more rows exist
than limit (max 500). Example:
SELECT slug, name, date, city FROM races WHERE state='CO'
AND distance_category='100M' AND date >= date('now') ORDER BY date
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description adds real substance on top: exactly one statement per call, only the three whitelisted views are queryable, and `truncated` signals that more rows exist than `limit`. The result shape (columns + rows) is disclosed even though no output schema exists.
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 hard constraint (one read-only SELECT) and the queryable views land in the first sentence; the truncation caveat and a concrete example follow. Nothing is padded — the example earns its space for a free-form SQL tool.
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 two-parameter tool with no output schema, the description covers dialect, scope, view whitelist, result shape, and truncation semantics. It stops short of saying what happens on invalid SQL or whether non-whitelisted objects error out, which an agent would still want to know.
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?
With 0% schema description coverage the description must carry both parameters, and it does for `sql` (SQLite dialect, read-only single SELECT, view names, plus a working example) and for `limit` (max 500, drives `truncated`). The default of 100 is left to the schema, a minor omission.
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: run one read-only SQL SELECT over the named views `races`, `editions`, `sources`. Naming the exact view whitelist and dialect (SQLite) makes it unambiguously distinct from `search_races` or `get_race`, which are structured lookups.
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?
Clear context is set — single statement, read-only, limited to three views, rows capped at 500 — which implicitly bounds when this is appropriate. It never explicitly says when to prefer `search_races` or `describe` over hand-written SQL, so the agent must infer that split from the sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a public web page the way this server reads it when it checks a quote:
its visible text and its links. Use it before propose_correction to copy an
exact quote, or to read a race page your own tools cannot open. find returns
only the passages around that text. A value that is a URL (website_url,
registration_url) can be shown by a link: quote the sentence that holds it.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| find | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. Beyond that, the description adds real behavioral content: output is scoped to visible text plus links (not raw HTML or scripts), and a sibling mode ('find') returns only surrounding passages. It stops short of disclosing failure modes for unreachable, paywalled or JS-rendered pages.
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 is front-loaded and efficient, but the closing sentence ('A value that is a URL (website_url, registration_url) can be shown by a link: quote the sentence that holds it') is syntactically tangled and reads as guidance about the correction workflow rather than about this tool. It costs clarity in a description that is otherwise tight.
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 only two parameters, full annotation coverage and no output schema, the description supplies what an agent needs: what comes back (visible text and links), what 'find' narrows, and the main use case. It leaves out edge-case behavior for blocked or non-public pages, which is the remaining gap for an openWorld fetcher.
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 0%, so the description must carry both parameters. It explains 'find' well ('returns only the passages around that text'), but 'url' is only implied by the opening sentence — no statement that it must be an absolute public URL or what happens with non-public targets. Partial compensation for a two-parameter schema lands at the 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?
The description uses a specific verb ('Read') on a specific resource ('a public web page') and goes further to state the exact output shape: 'its visible text and its links.' It also distinguishes itself from siblings by framing the read as 'the way this server reads it when it checks a quote,' which is a sharper identity than a generic page fetcher.
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 two concrete triggering situations: 'Use it before propose_correction to copy an exact quote' and 'to read a race page your own tools cannot open,' the latter implicitly distinguishing it from get_race. It does not explicitly rule out other siblings (search_races, query) or state when not to use it, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report something a single value cannot fix: a cancelled or discontinued race, two rows for the same race, a race filed under the wrong distance. Include a source and quote when you have one.
| Name | Required | Description | Default |
|---|---|---|---|
| note | Yes | ||
| slug | Yes | ||
| quote | No | ||
| source_url | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already state readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the safety profile is largely covered. The description is consistent with those annotations but adds little about what happens to a submitted report, whether it is reviewed, or what confirmation is returned.
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 two tight sentences, front-loads the core purpose, and uses examples efficiently. There is no wasted text.
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 four-parameter reporting tool with no output schema and no parameter descriptions, the description is too sparse. It explains the kind of problem to report but leaves the required inputs and the outcome of reporting unclear.
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 0%, so the description must explain the four parameters. It only hints that quote and source_url are optional supporting evidence and does not explain what note should contain or what slug identifies.
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 action, reporting a problem, and clarifies scope with examples such as cancelled races, duplicate rows, and wrong distance. This distinguishes it from a simple single-value correction, though it does not explicitly name the sibling propose_correction.
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 phrase 'something a single value cannot fix' gives a clear usage boundary, and the examples make the intended cases concrete. It does not explicitly say when to use propose_correction instead, but the contrast is strongly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find races. text matches the name, city or start location; state is a
two-letter code; distance_category is one of the values in describe; dates
are yyyy-mm-dd and filter the current edition's date. Returns the main columns;
use get_race for everything about one race.
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | ||
| limit | No | ||
| state | No | ||
| date_to | No | ||
| date_from | No | ||
| distance_category | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context by disclosing that results are a truncated projection ('Returns the main columns') and pointing to get_race for the complete record. It omits pagination behavior and the default limit of 25, which keeps it from a 5.
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 tight sentences, front-loaded with the purpose before parameter semantics, then ending on the sibling routing. Every clause carries information an agent needs; there is no restatement of the name or title.
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 0% schema coverage, no output schema and six optional parameters, the description supplies enough to call the tool correctly for five of the six params and clarifies the return scope. The unexplained `limit` (default 25, no stated maximum) is the only meaningful gap in an otherwise complete definition.
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 0%, so the description must compensate, and it largely does: it defines `text` matching fields, `state` as a two-letter code, `distance_category` as an enum sourced from `describe`, and the date format (yyyy-mm-dd) plus what the dates filter. Only `limit` is left unexplained, despite having a non-obvious default of 25.
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 ('Find races') and immediately qualifies the matching semantics of the filters. It explicitly distinguishes itself from get_race ('use `get_race` for everything about one race'), so an agent can separate the search tool from the detail tool without reading 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?
Gives clear routing guidance to two siblings: get_race for full detail on a single race, and describe as the source of valid distance_category values. It does not address when to prefer the sibling `query` tool, and there is no explicit 'do not use for X' statement, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
describeget_racepropose_correctionpropose_racequeryread_sourcereport_problemsearch_racesCash-pay MRI prices at 5,419 US hospitals.
Free fan-convention data for AI agents: dates, registration windows & table costs, US & Canada
Trail and ultra running: your Sigwren training, plus race courses, pacing and fuelling for anyone.
US local businesses, services and source-cited prices, city by city. Free, no API key.
Add one secure layer between your agents and this server.