CourseProfiler

Import course

import_course

Import a fetchable official GPX/FIT/CRSProf URL, official ZIP containing exactly one GPX, uploaded source_file artifact, raw JSON payload, or inline/proxied course_file into a CRSProf artifact. Third-party route hosts such as Wikiloc may return 403 to server fetches; when a URL is blocked, ask the user to download/upload the file through POST /api/artifact-uploads outside MCP and pass the returned source_file artifact ID as source.kind=artifact. For structured answers about a supplied activity, prefer analyze_activity. This is the lower-level artifact-only import; no catalog search, runner profile, or waypoint enrichment is required. For named race planning without a supplied source, search the catalog first.

Input Schema

Name	Required	Description
`source`	No
`options`	No
`course_file`	No	Inline/proxied GPX, FIT, CRSProf, or ZIP-with-one-GPX file object to import into CRSProf. Use content for text GPX/XML/JSON/CRSProf, base64 for FIT/ZIP/binary, or url only when the URL is fetchable by CourseProfiler. Bare local filesystem paths and file:// URLs are rejected; hosted clients that cannot proxy file bytes must use the REST POST /api/artifact-uploads flow outside MCP first, then pass the returned source_file artifact via source.kind=artifact.

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 / options / additionalProperties
```
Previous value: -trueNew value: +false
```

addedInput schema / properties / 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 / options / required
```
Added value: +[]
```

First observedJul 14, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already declare this is a non-read-only, open-world, non-idempotent mutation with destructiveHint=false. The description adds meaningful behavioral context beyond that: third-party hosts may block server fetches with 403, the out-of-band artifact-upload workaround, and that no catalog search/runner profile/waypoint enrichment is performed. It does not, however, state whether re-importing the same source is safe or what happens to an existing artifact, which would round this out.

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?

Dense but front-loaded: the accepted input types come first, then the failure/fallback behavior, then the sibling routing. It is longer than ideal and repeats the artifact-upload fallback that also appears in the course_file schema description, but nearly every sentence carries actionable information.

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

Completeness4/5

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

For a mutation tool with an output schema (so return values need no explanation) and partial annotation coverage, the description supplies the operational context an agent needs: accepted formats, the 403 fallback, and sibling routing. The main residual gap is the absence of any statement about re-import/idempotency behavior or the fate of pre-existing artifacts.

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 description coverage is only 33%, so the description must compensate, and it does: it maps input mechanisms to source kinds (URL vs ZIP vs uploaded artifact vs raw JSON) and explicitly explains the source.kind=artifact path for blocked URLs. It does not fully disambiguate source vs course_file or the options object, but it adds real value over 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?

Opens with a specific verb ('Import') and enumerates exactly what resources are accepted (GPX/FIT/CRSProf URL, ZIP, artifact, raw JSON, course_file) and the output artifact type (CRSProf). It explicitly distinguishes itself from analyze_activity and catalog search, so an agent can route correctly without opening a sibling schema.

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?

Gives explicit when-to-use and when-not-to-use guidance: prefer analyze_activity for structured answers about a supplied activity, search the catalog first for named race planning without a supplied source, and use the POST /api/artifact-uploads fallback when a host returns 403. Alternatives and selection conditions are all named.

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?