CourseProfiler

Create race plan

create_race_plan

Primary CourseProfiler tool for creating a personalized race plan and optional PDF. Use this after obtaining both a course input and runner input. Course input may be course_file, course.source with kind=url/artifact/raw_file, or course.crsprof_artifact_id. Do not use raw_json or reconstruct/synthesize a course from roadbooks, checkpoint tables, elevation profiles, aid-station lists, or screenshots; those are enrichment/context only and are not valid course geometry. Runner input may be runner_profile_file, runner.sources, or an already-converted runner.usrprof_artifact_id. Use generate_runner_profile for user-approved evidence or uploaded .usrprof source_file artifacts; do not silently use all local files. Ask about intent only when unclear; profile_intent does not perform server-side selection. Hosted MCP cannot read local paths: use inline content/base64 or REST POST /api/artifact-uploads and pass source_file artifacts through sources, not usrprof_artifact_id. There is no raw-byte MCP upload tool. get_artifact_upload_requirements and get_runner_profile_requirements explain files, evidence, and Strava consent. If the user provides only a race name, check the CourseProfiler race catalog manifest first, but do not rely on uniqueness alone: confirm the catalog match is the same event/course/location before using its assetPath CRSProf URL. Auto-resolution only uses exact/strong catalog matches; weak matches require explicit confirmation or an explicit course.source URL/artifact. Use search_race_catalog first when the user may need to choose among multiple matching catalog courses or when the match confidence is not clearly exact/strong. If no catalog match exists, try to resolve it to a fetchable official GPX/FIT/CRSProf URL or ask the user to upload/provide the course file or URL; do not stop at the race name. Third-party route hosts such as Wikiloc may return 403 to server fetches. If an official or third-party GPX/FIT/CRSProf URL cannot be fetched or is blocked, stop and ask the user to download the official file and upload it through POST /api/artifact-uploads, then continue with the returned source_file artifact ID. Do not create a race plan until a real route file/trusted CRSProf is available. Use import_course to create a CRSProf, enrich_course_waypoints to add structured aid stations/resources/cutoffs, then generate_course_segments before creating the race plan. Catalog CRSProf files may already include official waypoints/resources/cutoffs; if they do not, call enrich_course_waypoints or ask the user for structured aid/resource/cutoff data before segmentation. If official pages and regulation PDFs disagree, or exact aid locations are not fully listed in machine-readable form, ask the user to confirm and include only confirmed aid stations; do not invent missing locations. Route-only plans are incomplete unless the user explicitly accepts missing aid/resource details. If browsing/search is available, prefer the catalog first, then official race sources and direct GPX links over generic home pages; course-only pacing is incomplete without waypoint/resource enrichment. If runner data is missing, ask for a USRProf file/artifact or runner evidence, explain that the profile drives estimated times plus insights such as uphill running limit, durability/fatigue tendencies, downhill sensitivity, and terrain strengths/weaknesses, generate a segment-evidence runner profile with generate_runner_profile after user-approved evidence selection, and do not invent personalized fitness data. This race-plan flow creates a personalized plan/PDF only; it does not submit the course to the public catalog and does not need to. Only call submit_course when the user explicitly asks to submit/add/update a course for catalog review. Returns a top-level job with artifact role metadata; use get_job to poll and get_artifact to fetch outputs.

Input Schema

Name	Required	Description
`pdf`	No
`course`	No
`runner`	No
`estimate`	No
`race_name`	No	Race/course name to resolve through the CourseProfiler catalog when no course source is provided, e.g. Val d'Aran PDA.
`course_file`	No	Use this only when the MCP client provides an inline/proxied GPX, FIT, CRSProf, or ZIP-with-one-GPX file object. Provide content for text GPX/XML/JSON/CRSProf, base64 for FIT/ZIP/binary, or a fetchable URL. Bare local filesystem paths and file:// URLs are rejected. Hosted clients with local files must use the REST POST /api/artifact-uploads flow outside MCP and pass the returned source_file artifact as course.source.kind=artifact.
`runner_profile_file`	No	Use this only when the MCP client provides an inline/proxied USRProf runner profile file object. Provide content for text USRProf/JSON or base64 for binary. Personalized plans require runner input. Bare local filesystem paths and file:// URLs are rejected. Hosted clients with local .usrprof files should use POST /api/artifact-uploads and pass the returned source_file artifact via runner.sources[{kind:'artifact'}], not usrprof_artifact_id.

Output Schema

Name	Required	Description
`errors`	No
`job_id`	Yes	CourseProfiler job ID to poll with get_job.
`status`	Yes	Job status, e.g. queued, running, succeeded, or failed.
`progress`	No
`warnings`	No
`created_at`	No	ISO-8601 creation timestamp.
`expires_at`	No	ISO-8601 expiration timestamp.
`started_at`	No	ISO-8601 start timestamp, when available.
`status_url`	No	Relative API URL for polling this job.
`completed_at`	No	ISO-8601 completion timestamp, when available.
`result_artifacts`	No	Artifacts produced by the job, including role metadata.
`submission_request_id`	No	Request ID that originally allocated this job; absent in legacy metadata.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 14, 2026

addedOutput schema / properties / submission_request_id

Added value: +{
+  "description": "Request ID that originally allocated this job; absent in legacy metadata.",
+  "type": "string"
+}

Changed1 schema field changedSep 22, 2026

changedOutput schema / properties / result_artifacts / items / properties / download_url / description

Previous value: -"Private short-lived download URL. Share only with the user."New value: +"Artifact download URLs are private and short-lived; share them only with the user, verbatim in a code block, not a clickable link. Ask the user to copy the entire URL into their browser address bar. Do not rewrite the URL or add tracking parameters such as utm_source: changes invalidate the signature. If expired, call get_artifact for a fresh URL. This applies only to artifact download_url values, not authorization or upload links."

Changed3 schema fields changedSep 7, 2026

changedInput schema / properties / course / properties / import_options / additionalProperties
```
Previous value: -trueNew value: +false
```

addedInput schema / properties / course / properties / import_options / properties

Added value: +{
+  "include_routes": {
+    "description": "Include routes when analysing GPX/FIT. Existing CRSProf is preserved with analysis_options_not_applied warning.",
+    "type": "boolean"
+  },
+  "include_segments": {
+    "description": "Generate segments when analysing GPX/FIT. Existing CRSProf is preserved with analysis_options_not_applied warning.",
+    "type": "boolean"
+  }
+}

addedInput schema / properties / course / properties / import_options / required
```
Added value: +[]
```

First observedJul 14, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already declare the safety profile (not read-only, open-world, non-idempotent, non-destructive), but the description adds materially more: it creates a plan/PDF only and has no catalog side effect, it returns an async top-level job to poll with get_job and fetch with get_artifact, hosted MCP cannot read local paths and must use /api/artifact-uploads, and third-party hosts may 403 server fetches. This is rich behavioral context beyond the structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded, but the body is a ~450-word wall of text with duplicated guidance: the /api/artifact-uploads flow, the 'do not synthesize course geometry' prohibition, and the Wikiloc 403 warning each appear multiple times (and again in the schema). Several paragraphs read as general workflow policy for sibling tools rather than requirements for invoking this one, so size is poorly matched to the task.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter, deeply nested creation tool, the description leaves nothing essential out: inputs, prerequisites, sequencing, failure modes, upload path, async job handling, and what the tool deliberately does not do. With an output schema present, it correctly avoids enumerating return fields and instead points to get_job/get_artifact.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 43% (below the 50% threshold), so the description carries weight — and it does explain the critical distinctions: course_file vs course.source kinds vs course.crsprof_artifact_id, and runner.sources[{kind:'artifact'}] vs runner.usrprof_artifact_id, plus pdf being optional. However, nested options that are genuinely ambiguous (course.segments.mode generate/skip, estimate.options.strategy, import_options) get no mention, and the description repeats the 'stop and ask' URL guidance that already lives in the schema property text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource: 'creates a personalized race plan and optional PDF', and explicitly identifies itself as the primary CourseProfiler planning tool. It also draws boundaries against siblings (does not submit to the public catalog; use submit_course only when the user asks). An agent can distinguish it from export_race_plan_pdf, generate_course_segments, and submit_course without reading schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

States prerequisites ('use this after obtaining both a course input and runner input'), valid input forms for both course and runner, and explicit exclusions ('do not use raw_json or reconstruct/synthesize a course from roadbooks...'). It names alternatives and their conditions (generate_runner_profile, search_race_catalog, import_course, enrich_course_waypoints, generate_course_segments) and the sequence in which to call them.

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

All CourseProfiler tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?