Skip to main content
Glama

CourseProfiler

by com.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 runner.usrprof_artifact_id. Prefer generate_runner_profile first when the user has GPX/FIT/CRSProf activity evidence or an uploaded .usrprof source but no already-converted usrprof_artifact_id; then call create_race_plan with runner.usrprof_artifact_id. Before generating a runner profile for a race plan, resolve the target course if possible and ask the user whether the profile should be target-race-specific, target-distance/elevation-specific, general trail, or insights-only; select evidence that matches the intended distance, elevation gain/loss, terrain/technicality, altitude, duration, and recency. Do not silently use all files in a local folder. Use runner.usrprof_artifact_id only for an already-converted USRProf artifact; uploaded .usrprof/source_file artifacts from POST /api/artifact-uploads must be passed through runner.sources[{kind:'artifact'}] or through generate_runner_profile. Bare local filesystem paths never work in hosted MCP clients; send inline content/base64 when the MCP client can read the file, or use the REST POST /api/artifact-uploads flow outside MCP, complete the upload, then pass the returned source_file artifact ID. There is no raw-byte MCP upload tool; get_artifact_upload_requirements only explains the REST flow. Use get_runner_profile_requirements when the user needs instructions for creating/exporting a USRProf, using Strava/browser import, or uploading GPX/FIT/CRSProf evidence. 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

TableJSON Schema
NameRequiredDescriptionDefault
pdfNo
courseNo
runnerNo
estimateNo
race_nameNoRace/course name to resolve through the CourseProfiler catalog when no course source is provided, e.g. Val d'Aran PDA.
course_fileNoUse 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_fileNoUse 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

TableJSON Schema
NameRequiredDescriptionDefault
errorsNo
job_idYesCourseProfiler job ID to poll with get_job.
statusYesJob status, e.g. queued, running, succeeded, or failed.
progressNo
warningsNo
created_atNoISO-8601 creation timestamp.
expires_atNoISO-8601 expiration timestamp.
started_atNoISO-8601 start timestamp, when available.
status_urlNoRelative API URL for polling this job.
completed_atNoISO-8601 completion timestamp, when available.
result_artifactsNoArtifacts produced by the job, including role metadata.

TDQS

A4.7/5.0
Behavior5/5

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

With no annotations, the description carries the full transparency burden, and it delivers: it states the tool does not submit to the public catalog, only creates plan/PDF, blocks plan creation without a real route file, avoids inventing runner fitness data, and returns a top-level job to be polled via get_job and get_artifact. It also explains the artifact-upload flow limitations and third-party 403 behavior.

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

Conciseness3/5

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

The description is front-loaded with the main purpose and key exclusions, but it is a very long single paragraph with repetitive statements (e.g., the submit_course restriction appears twice, and the 'stop and ask the user to download/upload' flow is described multiple times). It could be tightened and organized without losing information.

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?

Given the tool's complexity, no annotations, and 15 sibling tools, the description is exceptionally comprehensive: it covers prerequisites, exact pre-processing pipeline, catalog resolution and confirmation, error handling for blocked fetches, runner-profile evidence selection, and output polling. It even notes when not to call submit_course, making the tool safe and self-contained.

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 low (43%), but the description compensates by explaining valid course sources (course_file, course.source kind=url/artifact/raw_file, course.crsprof_artifact_id), invalid raw_json course geometry, and runner sources (runner_profile_file, runner.sources, runner.usrprof_artifact_id). It clarifies when to use usrprof_artifact_id vs runner.sources artifacts and notes bare local paths fail, though segments/estimate options are largely left to the schema.

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?

Clearly identifies itself as the primary CourseProfiler tool for creating a personalized race plan and optional PDF. It further differentiates itself by specifying prerequisites (course + runner input) and naming companion tools like generate_runner_profile, making its scope unambiguous relative to siblings.

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?

The description gives explicit when-to-use guidance: only after course and runner inputs exist, and never by synthesizing course geometry from roadbooks or elevation profiles. It names concrete alternatives for sub-tasks (import_course, enrich_course_waypoints, generate_course_segments, generate_runner_profile, search_race_catalog) and tells the agent when to stop and ask for user-provided files.

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

All CourseProfiler toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.1/5.0
Disambiguation4/5

Each tool targets a distinct step in the course/race-planning workflow, and descriptions carefully separate concerns like importing, enriching, segmenting, and generating a plan. The main ambiguity is among the multiple get_*_requirements helpers, but their target phases are clear enough to avoid persistent misselection.

Naming Consistency5/5

All tool names follow a consistent verb_noun snake_case pattern (create_, enrich_, export_, generate_, get_, import_, search_, submit_, validate_). There is no mixing of camelCase or inconsistent verb styles, making the API predictable and easy to navigate.

Tool Count4/5

With 16 tools, the server is at the upper edge of the ideal range but each tool serves a distinct purpose in a complex pipeline covering course import, enrichment, segmentation, runner profiling, plan creation, PDF export, validation, and catalog submission. The count feels justified for the domain rather than bloated.

Completeness4/5

The toolset covers the full lifecycle from course discovery/import through enrichment, segmentation, runner profiling, race plan generation, PDF export, and catalog submission. Minor gaps exist, such as lack of artifact list/delete/update tools and no direct race-plan editing, but agents can work around these via get_artifact and get_job.

Resources