Measured race courses, open to all, and your own runs, Blocks and plans once you sign in.
Scored across 18 tools
Each course tool explicitly scopes a distinct slice (overview, amenities, route, terrain) and cross-references when to use the others; run tools separate splits, streams, laps, and interval detection with clear cross-links. No two tools have indistinguishable purposes.
All 18 tools share the 'ourpr_' prefix and snake_case, but verb patterns vary: get_/list_/plan_ for actions, while run_laps, run_stream, rep_workouts, training_blocks, similar_terrain are noun phrases. Still predictable and readable, only a minor deviation from pure verb_noun.
18 tools span several domains (courses, runs, plans, races, trails, training). The count is slightly above the ideal 3–15 range but each tool addresses a unique query type; no obvious redundancy.
Course, run, trail, and race surfaces cover read and some analysis; plans can be written via plan_week but lack MCP-level edit/delete. Missing run creation and plan update/delete are minor gaps given the server's apparent read/analysis focus.
Whether one particular run was an interval session, and its reps.
| Name | Required | Description | Default |
|---|---|---|---|
| activity_id | Yes | Run id from ourpr_list_runs. |
| Name | Required | Description |
|---|---|---|
| detection | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, fully covering the safety profile. The description adds no extra behavioral context such as performance characteristics, permissions, or data implications. Since it does not contradict the annotations, a 3 is appropriate given the annotation coverage.
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 a single, tightly written sentence: 'Whether one particular run was an interval session, and its reps.' It immediately states the purpose with zero waste, front-loading the core functionality. This is exemplary conciseness.
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 one parameter, a documented schema, an output schema, and rich annotations, the description is sufficient for an agent to call the tool correctly. It explains the purpose clearly, and the output schema presumably covers return details. It could add a note on what 'reps' specifically include, but this is a minor gap given the other structured information available.
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 parameter activity_id is well described as 'Run id from ourpr_list_runs.' The tool description adds no additional semantic detail beyond the schema, so it relies entirely on the schema's documentation. This meets the baseline for high schema coverage.
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 clearly states the tool's purpose: determining whether a specific run was an interval session and retrieving its reps. It uses a specific verb ('look for'/'detect') and resource (reps in a single run), and differentiates from siblings by focusing on a single run rather than list or general run tools. However, it does not explicitly name alternative tools, so it falls just short of a 5.
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 when you have a specific run ID and want to know if it was intervals, but it provides no explicit guidance on when to prefer this tool over siblings like ourpr_rep_workouts or ourpr_run_laps. There is no mention of alternatives or exclusions, leaving the agent to infer from the stated purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one published course: its place, distance, climb, how it was measured, and which streets carry it.
DELIBERATELY WITHOUT the elevation profile, the amenities and the centerline. Those are three more tools, because one course payload is about 83 KB and 91% of it is the profile.
Args:
slug (string): From ourpr_list_courses. Example: 'boston-marathon'.
response_format ('markdown' | 'json'): Default 'markdown'.
Returns: { "slug": string, "name": string, // the event's own name, title sponsor included "place": string | null, "alternate_names": string[], // curated geographic aliases "kind": string, "course_type": string, "distance_mi": number, // the stated race distance "measured_mi": number | null, // the centerline ourpr. measured "next_race_date": string | null, "days_out": number | null, "climb_ft": number | null, "descent_ft": number | null, "min_ft": number | null, "max_ft": number | null, "steepest_pct": number | null, "provenance": string | null, // one sentence on how it was built "sources": [{ "label": string, "value": string }], "recorded_on": string | null, // the watch that recorded the seed run "main_ways": [{ "name": string, "mi": number, "share_pct": number }], "through": string[], // named places the line passes through "photo_count": number, "counts": { "named_climbs_and_descents": number, "amenities": number, "mile_markers": number, "profile_points": number }, "page_url": string, "gpx_url": string }
distance_mi is what the race calls itself; measured_mi is what the centerline measures. They differ by a few hundredths and both are reported rather than reconciled.
Examples:
"Tell me about the Boston Marathon course" -> slug="boston-marathon"
"How much does San Diego climb?" -> slug="san-diego-marathon", read climb_ft
Do not use when: you want the hill-by-hill shape. Use ourpr_get_course_terrain.
Error handling:
Returns the slug list suggestion when the slug is unknown.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | The course's slug, exactly as ourpr_list_courses returns it. Example: 'boston-marathon'. | |
| response_format | No | Output format. 'markdown' reads well in a chat answer. 'json' carries every field for further computation. | markdown |
| Name | Required | Description |
|---|---|---|
| kind | Yes | |
| name | Yes | |
| slug | Yes | |
| place | Yes | |
| counts | Yes | |
| max_ft | Yes | |
| min_ft | Yes | |
| gpx_url | Yes | |
| sources | Yes | |
| through | Yes | |
| climb_ft | Yes | |
| days_out | Yes | |
| page_url | Yes | |
| main_ways | Yes | |
| descent_ft | Yes | |
| one_way_mi | Yes | |
| provenance | Yes | |
| course_type | Yes | |
| distance_mi | Yes | |
| measured_mi | Yes | |
| photo_count | Yes | |
| recorded_on | Yes | |
| steepest_pct | Yes | |
| next_race_date | Yes | |
| alternate_names | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds substantial context beyond that: why fields are omitted (83 KB payload, 91% profile), the deliberate reporting of both distance_mi and measured_mi without reconciliation, and the slug-unknown error behavior.
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 main purpose and exclusions are front-loaded in the first sentences, and the detailed Returns block is justified for a data-rich tool. However, the block is quite long and includes many inline comments that could be trimmed slightly without losing value.
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, idempotent tool with an output schema, the description is complete: it gives examples, error handling, sibling routing, field semantics, and format guidance. Nothing an agent needs to select and invoke it correctly 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 description coverage is 100%, so both parameters are already fully documented. The description adds useful context like the slug source ('From ourpr_list_courses') and the purpose of response_format, but this is incremental rather than essential.
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 opens with a specific verb and resource: 'Read one published course' and then enumerates exactly the fields it returns. It explicitly distinguishes itself from siblings by stating it is deliberately without elevation profile, amenities, and centerline, and that those are separate tools.
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 provides clear usage context with examples and an explicit 'Do not use when' for terrain, naming ourpr_get_course_terrain as the alternative. It notes that amenities and route data live in 'three more tools' but does not name those specific sibling tools, so routing is not fully comprehensive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Public drinking water and toilets on the line of one course, each placed at the mile it sits at.
READ THIS LIMIT BEFORE YOU ANSWER. These come from OpenStreetMap: public taps and toilets somebody mapped near the route. It is a FREQUENCY difference, not a category one — a race day sets up many more stops than an ordinary day has. A mapped tap can also be seasonal, shut off or gone. Never present this as an aid-station plan, and never imply the count is guaranteed.
It answers the training question instead: if I run this course on an ordinary day, where can I drink?
Args:
slug (string): From ourpr_list_courses.
response_format ('markdown' | 'json'): Default 'markdown'.
Returns: { "slug": string, "name": string, "distance_mi": number, "source": string, "is_race_aid_station_list": false, "water_count": number, "toilet_count": number, "longest_gap_without_water_mi": number | null, "longest_gap_from_mi": number | null, "longest_gap_to_mi": number | null, "amenities": [{ "kind": string, "mi": number, "lat": number, "lng": number }], "page_url": string }
The longest gap counts the start and the finish as ends, so a course with one water stop at mile 3 of 6 reports a 3 mile gap, not 0.
Examples:
"Where can I refill on the Cowtown ultra?" -> slug="cowtown-ultra-marathon"
"How far do I go without water on Boston?" -> read longest_gap_without_water_mi
Do not use when: you want race-day aid stations. ourpr. does not hold those.
Error handling:
A course with no mapped amenity returns empty arrays and zero counts. That means none is mapped, not that none exists.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | The course's slug. | |
| response_format | No | Output format. 'markdown' reads well in a chat answer. 'json' carries every field for further computation. | markdown |
| Name | Required | Description |
|---|---|---|
| name | Yes | |
| slug | Yes | |
| source | Yes | |
| page_url | Yes | |
| amenities | Yes | |
| distance_mi | Yes | |
| water_count | Yes | |
| toilet_count | Yes | |
| longest_gap_to_mi | Yes | |
| longest_gap_from_mi | Yes | |
| is_race_aid_station_list | Yes | Always false. These are public amenities, not race aid stations. |
| longest_gap_without_water_mi | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly and idempotent annotations, the description discloses critical behavioral nuances: the data source is OpenStreetMap, mapped taps may be seasonal/shut off/gone, and empty arrays mean 'none mapped' not 'none exist.' This adds essential interpretive guardrails that the annotations alone do not convey, and there is no contradiction with the readOnlyHint.
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 well-structured with clear sections (overview, limitations, args, returns, examples, error handling) and front-loads the core purpose. While it is longer than average, every sentence earns its place by addressing a specific concern or clarifying usage. The formatting aids scanability despite the length.
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 an output schema present, the description focuses on higher-level context: it explains the limitations, the training-use case, the 'Do not use' condition, and the meaning of empty results. Combined with the output schema and annotations, an agent has all necessary information to invoke this tool correctly and interpret its results. Nothing critical 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 the baseline is 3. The description adds value by specifying the slug should come from ourpr_list_courses and clarifying the response_format semantics ('markdown reads well in a chat answer, json carries every field for further computation'). This extra context makes the parameters more actionable than the schema alone, justifying a 4.
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 clearly states the tool's function: returning public drinking water and toilets on a course, positioned by mile. It explicitly differentiates from race-day aid stations, which distinguishes it from sibling tools like ourpr_get_course_route or ourpr_get_course_terrain. The title and verb align perfectly with the detailed purpose.
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 explicitly says when to use this tool ('if I run this course on an ordinary day, where can I drink?') and when not to ('Do not use when: you want race-day aid stations'). It also provides two concrete examples that map natural language queries to intended use, leaving no ambiguity about the selection context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Where a course actually runs: its start, its finish, its bounding box, every mile marker, and the streets in the order you meet them.
The GPX file is free and needs no account. Hand gpx_url to a person who wants the course on a watch.
Args:
slug (string): From ourpr_list_courses.
include_polyline (boolean): Add the encoded centerline, about 9,800 characters. Default false.
response_format ('markdown' | 'json'): Default 'markdown'.
Returns: { "slug": string, "name": string, "course_type": string, "distance_mi": number, "start": { "lat": number, "lng": number } | null, "finish": { "lat": number, "lng": number } | null, "bbox": { "min_lat": number, "min_lng": number, "max_lat": number, "max_lng": number } | null, "mile_markers": [{ "mile": number, "lat": number, "lng": number }], "streets_in_order": [{ "name": string, "from_mi": number, "to_mi": number }], "polyline": string | null, "gpx_url": string, "page_url": string }
On an out-and-back the start and the finish are the same point, by design.
Examples:
"Send me the Boston course for my watch" -> read gpx_url
"What streets does Dallas run down?" -> read streets_in_order
"Where does Honolulu start?" -> read start
Error handling:
Returns the slug list suggestion when the slug is unknown.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | The course's slug. | |
| response_format | No | Output format. 'markdown' reads well in a chat answer. 'json' carries every field for further computation. | markdown |
| include_polyline | No | Add the encoded centerline. It runs to about 9,800 characters and only helps if you will decode it. Leave it off and hand over `gpx_url` instead. |
| Name | Required | Description |
|---|---|---|
| bbox | Yes | |
| name | Yes | |
| slug | Yes | |
| start | Yes | |
| finish | Yes | |
| gpx_url | Yes | |
| page_url | Yes | |
| polyline | Yes | |
| course_type | Yes | |
| distance_mi | Yes | |
| mile_markers | Yes | |
| streets_in_order | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds that the GPX file is free and requires no account, and notes that on out-and-back courses start and finish coincide. It also discloses error behavior (returns slug list on unknown slug). These are valuable behavioral details beyond annotations, though rate limits are not mentioned.
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 well-organized with sections for purpose, args, returns, examples, and error handling. Every sentence adds value, from the GPX note to the out-and-back edge case. It is efficient and front-loaded with the core purpose.
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?
The description includes an inline return schema, examples, error handling, and an edge case. For a read-only tool with three parameters and annotations covering safety, this is comprehensive. An agent has everything needed to call it correctly.
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 provenance for slug ('From ourpr_list_courses') and clarifies the polyline's size and when to use it. The response_format guidance (markdown for chat, json for computation) adds meaning beyond the enum definition.
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 opens with a precise statement of what the tool returns: start, finish, bounding box, mile markers, and streets in order. This clearly identifies the course route as the resource and distinguishes it from sibling tools like amenities or terrain. The title 'Get a course's line' reinforces the purpose.
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 includes concrete examples mapping natural-language queries to output fields (e.g., 'Send me the Boston course for my watch' -> gpx_url). However, it does not explicitly contrast this tool with siblings like ourpr_get_course_amenities or ourpr_get_course_terrain, leaving routing to inference. The examples provide useful context but lack explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The elevation profile of one course, sampled, plus every climb and descent ourpr. named on it.
THIS IS THE TOOL FOR "what are the hills and where". Each named section carries the street it runs on, the miles it spans, its net rise or fall and its average grade.
The elevation comes from a public terrain model sampled along the measured centerline (elevation_source names it), not from a watch barometer. A barometer drifts; the model is checked against published race figures.
Args:
slug (string): From ourpr_list_courses.
points (number): Elevation samples to return, 2 to 200. Default 40. The stored profile holds up to 4,873.
response_format ('markdown' | 'json'): Default 'markdown'.
Returns: { "slug": string, "name": string, "distance_mi": number, "climb_ft": number | null, "descent_ft": number | null, "min_ft": number | null, "max_ft": number | null, "steepest_pct": number | null, "climb_ft_per_mi": number | null, "elevation_source": string, "profile_points_stored": number, "profile": [{ "mi": number, "ft": number }], "named_sections": [{ "kind": "climb" | "descent", "name": string, "from_mi": number, "to_mi": number, "net_ft": number, "grade_pct": number }], "page_url": string }
The sampled profile always keeps the first point, the last point, the highest and the lowest, so its extremes agree with min_ft and max_ft.
A course with no named sections returns an empty array. That means the seeder found no stretch that qualified, not that the course is flat: read climb_ft.
Examples:
"What are the hills on Boston?" -> slug="boston-marathon"
"Is Houston flat?" -> slug="houston-marathon", read climb_ft_per_mi
"Give me the profile in detail" -> points=200
Error handling:
Returns the slug list suggestion when the slug is unknown.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | The course's slug. | |
| points | No | How many elevation samples to return. The stored profile holds up to 4,873 points, which no agent should read whole. 40 describes the shape; 200 is close to the source. | |
| response_format | No | Output format. 'markdown' reads well in a chat answer. 'json' carries every field for further computation. | markdown |
| Name | Required | Description |
|---|---|---|
| name | Yes | |
| slug | Yes | |
| max_ft | Yes | |
| min_ft | Yes | |
| profile | Yes | Sampled elevation. The highest and lowest points are kept. |
| climb_ft | Yes | |
| page_url | Yes | |
| descent_ft | Yes | |
| distance_mi | Yes | |
| steepest_pct | Yes | |
| named_sections | Yes | |
| climb_ft_per_mi | Yes | |
| elevation_source | Yes | |
| profile_points_stored | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the read-only/idempotent annotations: it names the data source (public terrain model along measured centerline, not a watch barometer), explains why that matters (barometer drift, checked against published race figures), guarantees extremes are preserved in the sample, and documents the empty-array edge case and unknown-slug error behavior.
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-loaded with the routing statement and scoping, then args, returns and examples in scannable blocks. The inline Returns block largely duplicates the output schema, which is slightly wasteful, but each remaining sentence (sampling guarantee, empty-array meaning, error handling) 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?
For a read-only retrieval tool with a full output schema, this covers everything the agent needs: source provenance, sampling behavior, null-field handling, the empty named_sections ambiguity, format tradeoffs, and unknown-slug recovery. Nothing material 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 the baseline is 3, but the description adds practical guidance the schema lacks: the rationale for not reading all 4,873 stored points, what 40 vs 200 conveys, and that json is for further computation. It adds real decision value on top of the enum/default constraints.
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: the sampled elevation profile of one course plus every named climb and descent, and explicitly claims the 'what are the hills and where' niche. This separates it from ourpr_get_course and ourpr_get_course_route without opening 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 concrete query-to-parameter mappings ('What are the hills on Boston?' -> slug, 'Is Houston flat?' -> climb_ft_per_mi, 'profile in detail' -> points=200) and points to ourpr_list_courses for slug discovery. It does not explicitly say when to prefer a sibling such as ourpr_get_course_route, so it falls just short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One activity in full: mile splits with heart rate, cadence, calories, device. Id comes from ourpr_list_runs. For the profile along the route, use ourpr_run_stream.
| Name | Required | Description | Default |
|---|---|---|---|
| activity_id | Yes | Run id from ourpr_list_runs. |
| Name | Required | Description |
|---|---|---|
| run | Yes | |
| splits | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety behavior is covered without description help. The description adds a content hint about the returned detail, but since an output schema exists that enumerates return values, this is partly duplicative rather than genuinely new behavioral context.
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 tight sentences with zero filler; the payload contents are front-loaded and the routing hint to the sibling follows immediately. 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?
For a one-parameter read tool with a full output schema and rich annotations, the description covers what is returned, where the id comes from, and which sibling handles the adjacent use case. Nothing needed to invoke it correctly 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?
There is a single parameter at 100% schema coverage, and the description's only param statement ('Id comes from ourpr_list_runs') restates the schema description verbatim. It adds no format, constraint, or ID-shape guidance beyond what the schema already provides.
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 resource and scope ('One activity in full') and enumerates the returned detail (mile splits, heart rate, cadence, calories, device). It is clearly differentiable from the sibling ourpr_run_stream, though it never uses an explicit retrieval verb and leans on the title for the action.
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 names the prerequisite source for the id ('Id comes from ourpr_list_runs') and explicitly routes the alternative use case to ourpr_run_stream for route profile data. No exclusion is given for other siblings (e.g. ourpr_run_laps), so it falls just short of a full when/when-not statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one trail system: how many miles of path it holds, how many ways were mapped, where it sits, and where the measurement came from.
Args:
slug (string): From ourpr_list_trail_systems. Example: 'trinity-trails'.
response_format ('markdown' | 'json'): Default 'markdown'.
Returns: { "slug": string, "name": string, "region": string | null, "total_mi": number, // every branch summed "mapped_ways": number | null, // OpenStreetMap ways in the network "source": string | null, // how the network and its coverage were built "bbox": { "min_lat": number, "min_lng": number, "max_lat": number, "max_lng": number } | null, "page_url": string }
total_mi counts the whole network. It is not a distance anyone runs in one go.
Examples:
"How many miles of trail are in Fort Worth?" -> slug="trinity-trails"
"Where does the network reach?" -> read bbox
Error handling:
Returns the slug list suggestion when the slug is unknown.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | The trail system's slug. Example: 'trinity-trails'. | |
| response_format | No | Output format. 'markdown' reads well in a chat answer. 'json' carries every field for further computation. | markdown |
| Name | Required | Description |
|---|---|---|
| bbox | Yes | |
| name | Yes | |
| slug | Yes | |
| region | Yes | |
| source | Yes | |
| page_url | Yes | |
| total_mi | Yes | |
| mapped_ways | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context beyond annotations: it clarifies that total_mi is the whole network, not a single runnable distance, and it explains the error behavior for unknown slugs. It doesn't mention rate limits or pagination, but those are not relevant for a single-resource read 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?
The description is well-structured and front-loaded: the first sentence states the core purpose, followed by clear Args, Returns, Examples, and Error handling sections. Every section earns its place, and the total length is appropriate for the tool's complexity. The use of a compact JSON return example is efficient.
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?
The tool has a rich output schema, full parameter documentation, and clear annotations. The description adds the missing context: how to get the slug, what the numbers mean, and what happens on error. An agent has everything needed to select and invoke this tool correctly without opening the schema.
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 schema already documents both parameters. The description adds value by telling the agent where to obtain the slug (from ourpr_list_trail_systems) and by giving a concrete example. It also explains the practical difference between 'markdown' and 'json' output formats, which goes beyond the schema's enum definition.
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 opens with a specific verb ('Read') and a clear resource ('one trail system'), then enumerates exactly what data is returned: miles, mapped ways, location, and source. It is easily distinguished from siblings like ourpr_get_course or ourpr_list_trail_systems, which operate on different resources or list multiple items.
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 explicitly tells the agent to get the slug from ourpr_list_trail_systems, provides concrete examples ('How many miles of trail are in Fort Worth?' -> slug='trinity-trails'), and explains when to use the response_format. It also covers error handling by stating that an unknown slug returns a slug list suggestion. This is strong, actionable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every running course published on ourpr., with its place, distance, climb and next race date.
Each course is a MEASURED centerline built from recorded runs, with elevation from a public terrain model: USGS 3DEP 10 m in the US, and the city's own 1 m model in Berlin. It is not a course map traced by hand.
START HERE. Every other course tool takes a slug, and this is where slugs come from.
Args:
query (string, optional): Match the name and the place. Partial, case-insensitive.
kind ('race' | 'trail' | 'route', optional): Keep one kind.
course_type ('loop' | 'out-and-back' | 'point-to-point', optional): Keep one shape.
min_distance_mi / max_distance_mi (number, optional): Bound the distance in miles.
upcoming_only (boolean): Keep only courses whose race date has not passed. Default false.
limit (number): 1 to 50. Default 20.
offset (number): Skip this many. Default 0.
response_format ('markdown' | 'json'): Default 'markdown'.
Returns: { "total": number, // matched the filters "count": number, // in this answer "offset": number, "has_more": boolean, "next_offset": number, // present when has_more "published_total": number, // every published course "courses": [{ "slug": string, // "boston-marathon" "name": string, // the event's own name, title sponsor included "place": string | null, // "Hopkinton → Boston, MA" "kind": string, "course_type": string, "distance_mi": number, "climb_ft": number | null, "steepest_pct": number | null, "next_race_date": string | null, // YYYY-MM-DD "days_out": number | null, // null once the date has passed "page_url": string }] }
The order is the race calendar: the soonest race first, then undated courses by distance.
Examples:
"What marathons does ourpr. have?" -> min_distance_mi=26
"Which race is next?" -> upcoming_only=true, limit=1
"Anything in Fort Worth?" -> query="fort worth"
Do not use when: you want the hills on one course. Use ourpr_get_course_terrain.
Error handling:
Returns "No course matched" with the filters echoed when nothing matches.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Keep only this kind. 'race' is a published event course, 'trail' is a trail segment, 'route' is an everyday loop. | |
| limit | No | The most courses to return. | |
| query | No | Match against the course name and its place. Case-insensitive, partial. Example: 'boston', 'fort worth', 'half'. | |
| offset | No | How many courses to skip. Use it with `next_offset`. | |
| course_type | No | Keep only this shape of course. | |
| upcoming_only | No | Keep only courses whose next race date is today or later. A course with no date is dropped by this filter. | |
| max_distance_mi | No | Keep only courses no longer than this, in miles. | |
| min_distance_mi | No | Keep only courses at least this long, in miles. | |
| response_format | No | Output format. 'markdown' reads well in a chat answer. 'json' carries every field for further computation. | markdown |
| Name | Required | Description |
|---|---|---|
| count | Yes | Courses in this answer. |
| total | Yes | Courses that matched the filters. |
| offset | Yes | |
| courses | Yes | |
| has_more | Yes | |
| next_offset | No | |
| published_total | Yes | Every published course, before any filter. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only/idempotent safety profile, and the description adds genuinely new behavioral context: the measured-centerline provenance and elevation model, the result ordering (race calendar, soonest first, then undated by distance), and the 'No course matched' error behavior. These are things an agent could not infer from the annotations or 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?
Well front-loaded: purpose, provenance, routing guidance, then args/returns/examples/errors. The Returns block duplicates the output schema field-by-field, which is unnecessary given the schema exists, but the rest is dense and earns its space.
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 nine-parameter listing tool with full schema coverage, an output schema, and annotations, nothing an agent needs is missing: routing, ordering, defaults, error behavior and examples are all present.
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%, so every one of the nine parameters is already documented with types, bounds, defaults and enum meanings in the schema. The description's Args block largely restates that, adding only unit emphasis (miles). Baseline 3 is appropriate.
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 ('List every running course published on ourpr.') and enumerates the important returned fields right up front. The 'START HERE. Every other course tool takes a slug' line distinguishes it from all slug-taking siblings, and the explicit exclusion points to ourpr_get_course_terrain.
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?
Explicit when-to-use ('START HERE', source of slugs), an explicit do-not-use case routed to a named sibling, and four worked examples mapping natural-language questions to parameter sets. This is about as complete as usage guidance gets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The runner's planned runs between two dates: day, name, miles, time, tag, the runner's note, whether a logged run fulfilled it, and whether ourpr. create wrote it. Read it before ourpr_plan_week so a new plan does not land on a day that already holds one.
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | No | Last day, YYYY-MM-DD. Default 13 days after the first. | |
| start_date | No | First day, YYYY-MM-DD. Default yesterday, so today is in the window in every time zone. |
| Name | Required | Description |
|---|---|---|
| plans | Yes | |
| end_date | Yes | |
| truncated | Yes | |
| start_date | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: the output reveals whether a logged run fulfilled a plan and whether 'ourpr.create' wrote it, and it warns about collision checking before planning.
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 focused sentences: the first states the core purpose and output contents, the second gives the critical usage instruction. No filler or redundant restatement of the schema.
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 a rich output schema, full parameter documentation, and strong annotations, the description covers the remaining essential context: what the response contains and why the agent should call it before planning. Nothing important is missing for correct invocation.
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 both start_date and end_date already explain format and default behavior. The tool description does not need to repeat parameter details; it adds no additional parameter semantics, so the baseline of 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 uses a specific verb ('List') with a precise resource ('the runner's planned runs') bounded by a date window, and enumerates the returned fields (day, name, miles, time, tag, note, fulfillment status, source). This clearly distinguishes it from sibling tools like ourpr_list_runs, which covers logged runs.
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 explicitly tells the agent to read this tool before ourpr_plan_week to avoid placing a new plan on a day that already has one. That is concrete, actionable guidance tied to a real pre-condition, going beyond general context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every race ourpr. finds in the history, newest first, tune-ups included: date, name, distance, time, pace and run id. Also the fastest result at 5K, 10K, half marathon and marathon among them.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Most rows to return. | |
| distance | No | Only races at this distance. |
| Name | Required | Description |
|---|---|---|
| races | Yes | |
| total | Yes | |
| fastest | Yes | |
| returned | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the description only needs to add context beyond safety. It adds ordering behavior ('newest first'), the inclusion of tune-ups, the returned fields, and the secondary fastest-result summary.
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, front-loaded with the core scope and ordering, followed by concrete output fields and the additional fastest-results behavior. Every clause adds useful information 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 list tool with an output schema and strong annotations, the description is nearly complete. The only mild gap is that it does not clarify how the distance filter interacts with the 'fastest result at 5K, 10K, half marathon and marathon' summary, which could be ambiguous when a distance filter is applied.
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%: limit has a clear 'Most rows to return' description and distance has 'Only races at this distance.' The tool description adds no additional semantics for these parameters, which is acceptable given the schema already carries the burden.
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 and resource: 'Every race... in the history, newest first, tune-ups included', and enumerates the returned fields. This clearly separates it from sibling list tools like list_runs or list_courses.
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 gives clear context for when to use this tool: when an agent needs race history, including tune-ups, with fastest-result summaries. It does not explicitly name alternative sibling tools or exclusions, but the scope is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Training history between two dates, newest first: date, local start, name, type, miles, pace, time, elevation, average heart rate, and on a runs-only list Friel's efficiency factor and the heartbeats each mile took. Start here for totals, streaks, trends, or finding a run. For one run's splits, use ourpr_get_run with an id from here.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Most rows to return. The answer says what it left out. | |
| end_date | Yes | Last day to include, YYYY-MM-DD. Example: 2026-06-30 | |
| start_date | Yes | First day to include, YYYY-MM-DD. Example: 2026-01-01 | |
| include_non_runs | No | Include rides, gym and other types. Runs only by default. |
| Name | Required | Description |
|---|---|---|
| runs | Yes | |
| returned | Yes | |
| truncated | Yes | |
| total_in_window | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety profile is covered. The description adds useful behavioral context: default runs-only filtering, newest-first ordering, and the extra fields on runs-only lists. Does not mention default limit or pagination behavior, which would be valuable. With annotations covering safety, a 3 is appropriate.
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-loaded with scope and content, followed by usage guidance and the sibling reference. Fairly dense and efficient, though the field enumeration is long. Every sentence adds value.
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?
Covers what the tool does, what it returns (fields listed), when to use it vs. a sibling, and default filtering behavior. Output schema exists so return values needn't be explained. Minor gaps: default limit and pagination behavior aren't mentioned, but annotations cover safety.
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%, so all four parameters are documented in the schema (including limit, date formats, and include_non_runs behavior). The description adds nothing about parameter syntax or semantics. Baseline 3 is correct when schema does the heavy lifting.
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 (list) and resource (runs) with a clear scope (date range, newest first) and enumerates the fields returned. An agent can immediately distinguish this from ourpr_get_run or ourpr_run_laps.
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 usage guidance ('Start here for totals, streaks, trends, or finding a run') and explicitly names the alternative ('For one run's splits, use ourpr_get_run with an id from here'). Missing only explicit when-NOT-to-use exclusions, but the routing is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every trail system ourpr. maps. A trail system is a whole network of connected paths, measured end to end, not a single route through it.
Args:
response_format ('markdown' | 'json'): Default 'markdown'.
Returns: { "count": number, "trail_systems": [{ "slug": string, // "trinity-trails" "name": string, "region": string | null, // "Fort Worth, TX" "total_mi": number, // the whole network, all branches "page_url": string }] }
Examples:
"What trail networks does ourpr. map?" -> no arguments
"How big is Trinity Trails?" -> read total_mi, or call ourpr_get_trail_system
Do not use when: you want one measured route. Use ourpr_list_courses with kind='trail'.
| Name | Required | Description | Default |
|---|---|---|---|
| response_format | No | Output format. 'markdown' reads well in a chat answer. 'json' carries every field for further computation. | markdown |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| trail_systems | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior, lowering the bar. The description adds value by clarifying the domain-specific meaning of 'trail system' and stating the return shape (count and array). It does not contradict annotations, though it repeats some schema details.
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 well-structured: a clear purpose sentence, then Args, Returns, Examples, and a 'Do not use when' note. It is front-loaded and each section earns its place, though the return schema partially duplicates the output schema.
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 tool with one optional parameter, an output schema, and strong readOnly/idempotent annotations, the description fully covers purpose, usage, disambiguation, and return semantics. Nothing an agent needs to call it correctly 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% and the single parameter response_format is fully documented in the schema with enum and default. The description only restates the default and adds a practical note about markdown vs json, which is marginal. Baseline of 3 is appropriate.
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 opens with a precise verb ('List') and a scoped resource ('every trail system'), and immediately differentiates from single routes by defining a trail system as a network of connected paths. This distinguishes it from sibling ourpr_list_courses without ambiguity.
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 gives explicit usage examples and includes a 'Do not use when' clause pointing to ourpr_list_courses with kind='trail' for single measured routes. This clearly routes the agent to the correct sibling in the ambiguous case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write one planned run, or a week of them, onto days still ahead. Each lands on the runner's week as a plan they can see, edit and remove. Needs a token made with the write scope and ourpr. create. Never logs a run.
| Name | Required | Description | Default |
|---|---|---|---|
| plans | Yes | One run, or up to fourteen. |
| Name | Required | Description |
|---|---|---|
| written | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint=false), non-idempotency, and non-destructiveness. The description adds value by specifying that plans are visible, editable, and removable, and that a token with 'write scope and ourpr. create' is needed. It also clarifies it does not log runs. However, it doesn't elaborate on behavior when plans already exist on the same date or on rate limits, which would further improve transparency.
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 carrying essential information: the primary action, the outcome, the authentication requirement, and an explicit exclusion. The description is front-loaded with the purpose and avoids any filler or redundancy.
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 tool that writes up to 14 plans with multiple fields, the description covers the core behavior, token requirement, and non-logging nature. It doesn't mention whether existing plans on the same date are replaced or appended, which could be relevant, but given the output schema is present (per context signals) and the schema already validates dates, the description is largely complete.
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 schema covers 100% of the parameter descriptions, so the baseline is 3. The description only loosely references the array ('one planned run, or a week of them') and doesn't add syntax or format details beyond the schema. It provides minor context that these are plans rather than logs, but overall the schema does the heavy lifting.
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 ('write') and resource ('planned run(s)') onto 'days still ahead', which clearly distinguishes it from the read-only sibling tools like ourpr_list_plans and ourpr_get_run. It also explains the result ('a plan they can see, edit and remove'), making the tool's purpose unambiguous.
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 gives clear context for when to use the tool (to put planned runs on the runner's week) and explicitly notes it 'Never logs a run', which implies a separate tool handles logging. It also states the required token scope ('write scope and ourpr. create'), which is a prerequisite. It doesn't name an alternative tool, but no sibling performs a similar write action, so this is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Interval sessions found across the history, with reps and distances. Detection is conservative, so a session it misses is still in ourpr_list_runs.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many recent activities to read. |
| Name | Required | Description |
|---|---|---|
| scanned | Yes | |
| workouts | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context by warning that detection is conservative, which complements the openWorldHint and helps the agent calibrate expectations about completeness.
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, front-loaded with the core purpose, and no filler. The cautious-detection caveat and the fallback to ourpr_list_runs are placed exactly where they add decision value.
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 one optional parameter, strong safety annotations, an output schema, and a clear detection-behavior caveat, nothing essential is missing for an agent to select and call this tool correctly.
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 single 'limit' parameter is fully documented in the schema. The description adds no extra parameter semantics, which is fine because the schema already carries the burden.
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 and resource ('Interval sessions found across the history') and adds the concrete payload ('with reps and distances'). It also differentiates itself from ourpr_list_runs by noting this tool only contains detected interval sessions, so an agent can tell what it returns.
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 gives clear practical guidance: detection is conservative, and any missed session is still available in ourpr_list_runs. This effectively names a fallback alternative, though it does not explicitly cover when to prefer this over the closely related sibling ourpr_detect_reps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The laps the watch recorded for one run — the runner's own button presses. Laps follow the workout; mile splits follow the mile.
| Name | Required | Description | Default |
|---|---|---|---|
| activity_id | Yes | Run id from ourpr_list_runs. |
| Name | Required | Description |
|---|---|---|
| laps | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only and idempotent nature of the operation, so the description does not need to establish safety. It adds useful behavioral context by explaining that laps are manually recorded button presses and that lap boundaries follow the workout rather than mile markers.
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 short sentences with no filler. The core definition is front-loaded, and the second sentence earns its place by distinguishing laps from mile splits, though it is slightly more poetic than necessary.
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 simple getter with one fully described parameter, robust read-only annotations, and an output schema, the description covers everything needed to select and call the tool. No prerequisites, side effects, or return-value details are 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?
The input schema fully documents the single required parameter activity_id and even states it comes from ourpr_list_runs. The description adds no parameter-specific detail, so with 100% schema coverage the baseline of 3 is appropriate.
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 title and description clearly identify the resource as the watch-recorded laps for a single run, with the clarifying phrase "runner's own button presses." It distinguishes manual laps from mile splits, though it does not explicitly name a sibling tool to differentiate against.
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 when to use this tool: when the agent needs manual button-press laps rather than mile splits. However, it never explicitly states when to choose this tool over siblings like ourpr_get_run or ourpr_run_stream, leaving some routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A run's profile on a 10 m grid — elevation, heart rate, power, cadence — as min, average, max and coverage per channel, not every sample. Also each half by distance with its moving pace, heart rate and efficiency, the pace change between them, and the drift (aerobic decoupling, Pa:HR), also after the warm up. No profile is a normal answer for an indoor run.
| Name | Required | Description | Default |
|---|---|---|---|
| activity_id | Yes | Run id from ourpr_list_runs. |
| Name | Required | Description |
|---|---|---|
| grid_m | Yes | |
| halves | Yes | |
| samples | Yes | |
| channels | Yes | |
| total_miles | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the safe read-only, idempotent profile, and the description adds genuinely new behavioral context: the result is aggregated rather than sample-level ('not every sample') and an empty profile is an expected outcome for indoor runs. That edge-case disclosure is exactly the kind of behavior an agent needs and cannot get from the annotations or 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?
The core deliverable (grid profile, min/avg/max/coverage) is front-loaded, followed by the half-split and drift details. It is somewhat clause-dense with the trailing 'also ... also after the warm up', but nearly every phrase conveys concrete field semantics 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?
With a rich output schema and full annotation coverage, the description's job is mostly done by structured fields; it nonetheless fills the most important gaps by naming the metrics returned and flagging the indoor-run empty case. Nothing critical for correct invocation appears 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?
There is a single parameter with 100% schema description coverage, and the schema already explains it ('Run id from ourpr_list_runs'). The description adds nothing about the parameter, so the baseline of 3 is appropriate when the schema fully carries 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?
The description precisely states what the tool returns: a 10 m grid profile with elevation and sensor channels summarized as min/avg/max/coverage, plus per-half distance splits and drift metrics. It is clearly distinct from sample-level siblings like ourpr_run_laps, though it never names those siblings explicitly, so the differentiation is implicit rather than stated.
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 explicit when-to-use guidance or routing to alternatives such as ourpr_get_run or ourpr_run_laps. The single line 'No profile is a normal answer for an indoor run' is about interpreting an empty response, not about when to call this tool versus another, so usage remains inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stretches of past runs matching a distance and climb — what the runner has already done that resembles a race they are training for.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many to return. | |
| miles | Yes | Target distance in miles. | |
| gain_ft | Yes | Target climb in feet. | |
| tolerance_ft | No | Climb tolerance, feet. |
| Name | Required | Description |
|---|---|---|
| matches | Yes | |
| scanned | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds purpose context but no additional behavioral details such as return format, pagination, or empty-result handling. No contradiction with annotations.
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 a single, compact sentence that front-loads the core function ('Stretches of past runs matching a distance and climb') before the explanatory clause. There is no redundant phrasing.
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 an output schema present, the description need not detail return values. It gives enough to understand the tool's intent, but it lacks guidance on typical use cases (e.g., race preparation) or any limitations. Adequate but not rich for a 4-parameter 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%, with every parameter (miles, gain_ft, limit, tolerance_ft) having a clear description. The tool description adds no parameter-level information beyond what the schema provides, so the baseline 3 is appropriate.
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 clearly states the resource ('past runs') and the purpose ('matching a distance and climb'), with an illustrative note about race training. It is specific and not a tautology, but it does not differentiate from sibling tools like ourpr_run_laps or ourpr_run_stream.
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?
No explicit guidance is given on when to use this tool versus alternatives. The race-training phrase implies a use case, but no exclusions or alternative tool references are provided, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The goal race and its Block: race day, distance, goal time, which week of the Block today falls in, and miles for each week. Also the Blocks before past races, each with its result, weeks and peak week. A Block is the race-anchored Monday to Sunday weeks before a race.
| Name | Required | Description | Default |
|---|---|---|---|
| past | No | How many past Blocks to include, newest first. |
| Name | Required | Description |
|---|---|---|
| goal | Yes | |
| past | Yes | |
| total_races | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds useful behavioral context by explaining the data returned, the concept of a Block, and that it computes which week of the Block today falls in. This goes beyond the annotations without contradicting them.
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 three sentences, front-loads the primary subject, and defines the key domain term 'Block' at the end. Every sentence adds value and there is no redundant or filler content.
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?
The description plus the output schema and annotations cover the essential information an agent needs: what data is returned, what a Block is, and how the past parameter behaves. It does not discuss edge cases like no past races or timezone handling for 'today', but these are minor for a read-only, idempotent retrieval tool with a well-documented schema.
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 single parameter 'past' is fully documented in the schema with description, default, and bounds. The description adds some related context by mentioning past race Blocks, but does not directly explain the parameter semantics beyond what the schema already provides. This matches the baseline for full schema coverage.
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 clearly states a specific resource ('goal race and training blocks') and enumerates exactly what is returned: race day, distance, goal time, current week, weekly miles, and past race blocks with results. This distinguishes it from sibling tools like ourpr_list_races or ourpr_plan_week, which cover different aspects of race/plan data.
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 makes the intended use obvious by naming the goal race and training block context. It does not explicitly mention when not to use it or name alternatives, but the content is specific enough that an agent can infer when this tool is appropriate. No misleading guidance is present.
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.
ourpr_run_stream2 fields changedOutput schema / properties / halvesAdded value: +{
+ "anyOf": [
+ {
+ "additionalProperties": {},
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ]
+}Output schema / requiredPrevious value: -[
- "grid_m",
- "total_miles",
- "samples",
- "channels"
-]New value: +[
+ "grid_m",
+ "total_miles",
+ "samples",
+ "channels",
+ "halves"
+]ourpr_detect_repsourpr_get_runourpr_list_plansourpr_list_racesourpr_list_runsourpr_plan_weekourpr_rep_workoutsourpr_run_lapsourpr_run_streamourpr_similar_terrainourpr_training_blocksourpr_get_courseourpr_get_course_amenitiesourpr_get_course_routeourpr_get_course_terrainourpr_get_trail_systemourpr_list_coursesourpr_list_trail_systemsRace course profiling, catalog search, course submission, and personalized race plans.
Manage your endurance training data and race preparation
Your swim, run and ride training, explained. For coaches and athletes, computed from Garmin data.
Heart-shaped GPS running routes in 200+ cities — charity, gift, memorial, anniversary.
Add one secure layer between your agents and this server.