Skip to main content
Glama

CourseProfiler

by com.courseprofiler
OverviewDiscussionsAdmin

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

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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • 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."
  2. Changed3 schema fields changed
    • 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: +[]
  3. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Annotations only provide generic hints (readOnlyHint=false, destructiveHint=false, etc.). The description adds substantial behavioral context: it warns that third-party hosts may return 403, explains that the tool does not submit to the public catalog, clarifies that it returns a job object to poll via get_job, and explicitly says it does not invent personalized fitness data. This goes well beyond what annotations convey, making behavior fully transparent.

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

Conciseness4/5

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

The description is very long, but it is front-loaded with the core purpose and then builds logically through input requirements, workflows, and fallbacks. While some sentences are repetitive (e.g., multiple warnings about not synthesizing course geometry), the density is justified given the tool's complexity. It could be slightly more structured, but it is not bloated with irrelevant content.

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?

The description covers the full workflow: prerequisites, valid input sources, what to do when data is missing, how to handle catalog matches, and what outputs to expect (job with artifact role metadata). It also explains how this tool fits into the broader pipeline (import → enrich → segment → plan). Given the output schema exists, return values are covered elsewhere. The description is complete for an agent to use this tool correctly without needing to inspect other tools.

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

Parameters5/5

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

With only 43% schema description coverage, the description compensates richly. It explains the distinction between course.source.kind=artifact and crsprof_artifact_id, clarifies that course_file is only for inline/proxied files and that hosted clients must use REST uploads, and details how race_name resolves through the catalog. It also clarifies when to use runner.sources versus usrprof_artifact_id. This is far beyond schema descriptions and gives the agent precise parameter usage semantics.

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?

The description opens with a specific verb-resource statement: 'Primary CourseProfiler tool for creating a personalized race plan and optional PDF.' It also clearly distinguishes itself from sibling tools by naming the prerequisites (course and runner input) and referencing related tools like import_course, enrich_course_waypoints, and generate_course_segments. The scope is unambiguous.

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?

Extremely explicit guidance: states when to use (after obtaining both inputs), what inputs are valid and invalid (e.g., 'Do not use raw_json or reconstruct/synthesize a course'), when to use generate_runner_profile, when to use search_race_catalog, and explicit exclusions ('Only call submit_course when the user explicitly asks'). It also explains fallback steps for failed fetches and missing data, leaving no ambiguity about when to invoke this tool versus alternatives.

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
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