CourseProfiler

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.

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.

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.

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.

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.

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.

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

With no annotations provided, the description carries the full burden and does well: it discloses that unsupported resource strings are ignored with warnings, that existing waypoints should be merged rather than duplicated, and that route-only plans should be labeled incomplete. It does not spell out persistence or side effects, but the 'Add to artifact' phrasing implies mutation and the warnings about ignored data are valuable behavioral 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 four sentences, front-loaded with the core purpose, and every sentence earns its place by addressing usage, duplicate avoidance, mode preference, and incompleteness labeling. There is no fluff or repetition of schema details.

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?

Given the tool's complexity (nested waypoints object, many enum options, no annotations) the description is quite comprehensive. It covers critical corner cases: existing waypoints, free-text resources, unsupported strings, and route-only plans. It does not mention return value format, but an output schema exists, so that is not required. A few minor gaps remain, such as explicit idempotency or confirmation behavior when official data is absent.

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 only 50%, but the description compensates by adding strategic guidance: prefer waypoints.mode=structured, place non-canonical details in notes/source text, and use table_url with caution ('verify results'). It also clarifies resource handling, which maps to the items.resources enum. This adds meaning beyond the raw schema, though it does not explain every nested field.

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: 'Add structured aid stations, checkpoints, cutoffs, and canonical resources to a CRSProf artifact that lacks them.' This clearly distinguishes the tool from siblings like generate_course_segments or validate_course_profile by focusing on enriching waypoint metadata. The scope is precise and 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 provides clear when-to-use context: enrich when the artifact lacks waypoints, inspect for existing GPX/CRSProf waypoints first, and avoid duplicates by merging/updating. It also advises preferring waypoints.mode=structured and marking route-only plans as incomplete unless official details exist. It does not explicitly name an alternative tool, but the guidance is strong enough for an agent to decide when to invoke this tool.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool only exports a PDF and that options are 'presentation-only overrides,' implying no mutation of the underlying artifact. It also clarifies the relationship between the artifact and options. This adds useful behavioral context beyond what the schema provides, though it does not discuss side effects or error scenarios.

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, each earning its place. The first states the action, the second clarifies the artifact vs. options relationship, and the third gives a critical usage pointer. It is front-loaded and has no redundant information.

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?

Given the tool's moderate complexity (two params, one nested object), the description is complete. It explains the source of data, the optionality and role of options, and a specific parameter omission rule. Since an output schema exists, return values need not be described. The description effectively covers all necessary context for an agent to select and invoke the 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 50% (only one of two top-level params has a description). The description compensates by explaining the roles of the parameters: crsprof_artifact_id supplies course/profile/plan data, and options are presentation-only overrides. It also adds a specific rule for unit_system. This adds meaning beyond the schema's basic field descriptions.

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: 'Export a Hi-Fi PDF from an existing CRSProf artifact.' It uses a specific verb+resource (Export PDF), names the required input (CRSProf artifact), and distinguishes the tool from siblings like create_race_plan or get_artifact by focusing on PDF export from an existing artifact.

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 context for when to use the tool: it requires an existing CRSProf artifact, implying it is not for creating or modifying plans. It also gives a specific parameter guideline ('Omit unit_system unless the user explicitly asks for metric or imperial.') and explains that options are presentation-only overrides. It does not explicitly name alternative tools, but the context is clear enough.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It states prerequisites (enriched or catalog CRSProf with official waypoints/resources/cutoffs) and clarifies that the generated artifact is not a catalog submission, which is a key behavioral caveat. However, it does not mention whether the input artifact is modified, what side effects occur, or error conditions, so it is not 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.

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

The description is compact and front-loaded with the core purpose, then adds essential usage context in two well-structured sentences. Every clause provides useful information without redundancy. The semicolon-separated flow makes the prerequisites and fallback behaviors easy to parse.

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?

Given the complexity of the options object and the absence of annotations, the description covers key contextual ground: when to use, what input is valid, how the output is used downstream, and a critical distinction from catalog submission. It does not explain the segmentation options themselves, but the output schema and schema field descriptions partially mitigate that. Overall, it is reasonably complete for a tool with many siblings and conditional usage.

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 has 50% coverage, and the description does not compensate for the gap. It does not explain what options like algorithm, flat_grade, or include_routes mean, nor does it elaborate on the crsprof_artifact_id beyond what the schema already states. The description adds minimal parameter-level meaning, leaving the many options underdocumented.

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: generating analytical course segments from an enriched CRSProf or a catalog CRSProf with official waypoints/resources/cutoffs. It distinguishes itself from downstream tools like create_race_plan and submit_course by explicitly positioning this as a prerequisite step. The verb 'generate' and the resource 'course segments' are specific and 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 explicit when-to-use guidance: use it after waypoint enrichment or with a catalog CRSProf that already contains official waypoints/resources/cutoffs. It also clearly states when to use alternatives, saying to call submit_course only if the user asked to submit for catalog review, and to use the result in create_race_plan for race planning. This is strong differentiation and practical usage direction.

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

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

With no annotations, the description carries full burden and delivers rich behavioral context: it explicitly says to ask the user before selecting evidence, not to silently use local files, describes server-side archive expansion with skipped nested archives, duplicate contents, unsupported entries, and parse failures, and details the Strava browser authentication flow including not asking for credentials. This exceeds what annotations would typically provide.

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 long, but every sentence earns its place given the tool's complexity. It is front-loaded with the core purpose, then logically progresses through pre-conditions, evidence types, Strava flow, and post-success handoff to create_race_plan. Slightly verbose but not redundant; the length is justified.

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?

Despite no annotations and low schema coverage, the description covers prerequisites, evidence selection strategy, archive behaviors, Strava handling, and the exact follow-up action (pass artifact ID to create_race_plan). An output schema exists, so return value documentation is unnecessary. The description is complete for an agent to correctly select and invoke the 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 coverage is only 33%, but the description compensates thoroughly. It explains accepted source types (GPX/FIT/CRSProf, archives, .usrprof), archive handling nuances, and the profile_intent concept (target race, target distance, general trail, insights-only). It also clarifies that import_options only supports segment_evidence. This adds substantial meaning beyond the raw schema.

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: 'Generate a segment-evidence USRProf runner profile artifact from uploaded runner evidence or an existing .usrprof source.' This clearly distinguishes it from sibling tools like create_race_plan and generate_course_segments, and it explicitly states when NOT to use it (when an already-converted usrprof_artifact_id exists).

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?

Provides explicit when-to-use guidance: 'Use this when the user does not already have an already-converted usrprof_artifact_id.' It also names alternatives and boundary conditions, such as not calling the tool merely to recreate a Strava-exported .usrprof, and instructs passing the resulting artifact ID to create_race_plan for race plans. This is far beyond minimal guidance.

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

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

With no annotations provided, the description carries the full burden. It adds key behavioral info beyond the schema: the URL is 'private' and 'short-lived', which signals expiration and access restrictions. It does not detail error behavior or auth requirements, but the core fetch semantics are well disclosed.

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 concise, information-dense sentence. It front-loads the main action (Fetch) and includes the key qualifiers (private, short-lived) without any wasted words.

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 one-parameter fetch tool with an output schema present, the description covers the essential purpose and key behavior. It does not need to explain return values since the output schema will provide that, and the low complexity means no additional context is required.

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 artifact_id is fully described in the schema with an example format (art_...), achieving 100% schema coverage. The description merely repeats 'by artifact_id' and adds no additional semantic detail, so 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?

Description uses a specific verb (Fetch) and resource (artifact metadata and private short-lived download URL), clearly scoped by artifact_id. It distinguishes itself from sibling tools like get_artifact_upload_requirements, which target upload requirements, not fetching an artifact.

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 you have an artifact_id and need its metadata or download URL. It does not explicitly exclude alternatives or name siblings, but the context is clear enough for an agent to select it over get_artifact_upload_requirements or get_job.

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

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

With no annotations provided, the description carries the full burden. It discloses that this is an 'instruction helper' and specifically not a raw-byte upload tool, and explains a limitation of hosted MCP. It does not explicitly state that it has no side effects, but the 'instruction helper' phrasing strongly implies a read-only, non-mutating 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 description is two sentences, front-loaded with the use case, and every word earns its place. It is compact without sacrificing clarity.

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 zero-parameter instruction tool with an output schema, this description is complete. It explains when to use it, what it provides, and what it does not do. The output schema covers return-value details, so the description need not elaborate further.

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 tool has zero parameters, and the schema is empty, so the baseline is 4. The description adds no parameter-specific meaning, but none is needed since the tool takes no inputs.

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 identifies the tool as providing instructions for CourseProfiler's REST artifact upload flow, using a specific verb ('get') and resource ('artifact upload requirements'). It explicitly distinguishes itself from a raw-byte MCP upload tool, differentiating it from siblings like get_artifact.

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 opens with 'Use this when' and provides two concrete scenarios: needing instructions for the upload flow or explaining why hosted MCP cannot upload bare local paths. It also includes a when-not by stating it is 'not a raw-byte MCP upload tool,' giving the agent clear boundaries.

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

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

With no annotations provided, the description must carry the full transparency burden. It uses 'Returns' which implies a read-only operation, but does not disclose any potential side effects, rate limits, or behavior when the course is not found. The description adds some context about the workflow but omits deeper behavioral details, making it minimally adequate.

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, dense sentence that front-loads the primary usage directive ('Use this before submit_course') and then concisely enumerates the return contents. No fluff or repetition; every phrase 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?

Given the 3 optional parameters and the presence of an output schema, the description covers the tool's purpose, when to use it, and outlines the return payload categories. It does not need to detail return values since the output schema exists. It could mention error scenarios or prerequisites, but for a requirements-gathering tool, it is sufficiently 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?

Schema coverage is 100% with all three parameters well-described. The description adds marginal value by framing the tool for 'incomplete inputs', but this is already inferable from the optional params (required: []). It does not provide additional meaning beyond the schema, so it stays at the baseline 3.

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 returns a 'catalog-first course submission workflow' and enumerates the specific content areas (accepted route sources, metadata, waypoint enrichment, upload requirements). It explicitly positions this as a pre-submission step, distinguishing it from submit_course and other requirement-gathering siblings like get_race_plan_requirements.

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?

Provides explicit usage context: 'Use this before submit_course when the user gives only a race name or incomplete inputs.' This makes the trigger condition clear, but it does not explicitly state when not to use it or name alternative tools for other scenarios, so it falls short of a 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Poll' but does not explain whether this returns the current status immediately, whether it blocks until completion, or how job states and errors are conveyed. This is a minimal disclosure for a polling 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 a single sentence that is concise and front-loaded. Every word contributes to the core purpose, and there is no redundant information.

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?

Given the tool's simplicity (one parameter, output schema present), the description is minimally viable but lacks usage context and behavioral details. It does not explain how to interpret polling results or when polling is necessary, leaving some gaps for an agent.

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 already provides 100% coverage for job_id with a clear description and example ('CourseProfiler job ID, e.g. job_...'). The description's mention of 'by job_id' adds no additional semantic meaning, so 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 description clearly states the action ('Poll') and the resource ('a CourseProfiler async job by job_id'), which distinguishes it from sibling tools like get_artifact or get_*_requirements. It is specific and 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 provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites like having previously initiated an async job. The phrase 'Poll' implies usage after job creation, but this is not explicit.

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

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

With no annotations provided, the description carries the transparency burden. It discloses that the tool returns required inputs and next steps, and conditionally includes catalog matches when available. It does not explicitly state it's read-only, but the 'get' prefix and context imply a non-destructive query, and the returned data is well described.

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 that immediately front-load the usage context, then state exactly what the tool returns. No filler, every word 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?

Given the simple nature (3 optional params) and that an output schema exists, the description is sufficiently complete. It explains when to use, what it returns, and the relationship to create_race_plan, so the agent can select and invoke it correctly without additional context.

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 all three optional parameters documented in the schema. The tool description adds overall usage context but does not provide additional semantics for individual parameters beyond what the schema already offers, so baseline 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 clearly states the tool's function with a specific verb 'Returns' and resource 'required course and runner inputs' plus 'next steps'. It distinguishes itself from siblings by explicitly referencing create_race_plan and mentioning catalog matches.

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?

Provides explicit when-to-use guidance: 'Use this before create_race_plan when the user gives only a race name or incomplete inputs.' This clearly frames the tool as a prerequisite/helper, differentiating it from the create_race_plan sibling.

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

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

With no annotations provided, the description carries full behavioral disclosure. It goes beyond a vague 'explains requirements' by listing specific content areas (file contents, activity types, upload processes). It does not explicitly state whether the tool is read-only, but for an informational requirements tool this is sufficient.

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 with no wasted words. The first sentence gives the when-to-use trigger; the second packs the tool's coverage into a compact, readable list. Front-loaded and 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 description covers the core user scenarios and an output schema exists to document return values. It could improve by linking to sibling tools like generate_runner_profile or validate_runner_profile, but it is complete enough for an informational 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?

The tool accepts zero parameters, so there is nothing for the description to add beyond the schema. The baseline for 0-parameter tools is 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 uses a specific trigger ('when runner input is missing or unclear') and enumerates the exact topics covered (USRProf/evidence files, GPX/FIT sufficiency, hosted MCP uploads). This clearly distinguishes it from sibling 'requirements' tools like get_race_plan_requirements or get_course_submission_requirements.

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 first sentence explicitly states when to use the tool. However, it does not mention alternatives or explicitly exclude cases; it could name what the user should do instead when runner input is not the issue.

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

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

No annotations exist, but the description discloses server fetch limitations (403 from Wikiloc/route hosts), the workaround (artifact-uploads flow), and the restriction to official sources and ZIP with exactly one GPX. It does not mention return format or permissions, but the output schema exists and mutation is implied by 'import'.

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?

Three sentences with zero fluff; the list of accepted formats is necessary and the workaround is essential. Front-loads with the verb 'Import' and resource.

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 complex tool with multiple source formats, nested objects, and an output schema, the description covers accepted inputs, the 403 edge case, and the correct sequence relative to other tools. Options remain unspecified, but it's an optional additionalProperties object and the key cases are covered.

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 only 33%, but the description enumerates the accepted source.kind variants (url, artifact, raw_json, raw_file), explains when to use artifact (blocked URL) and clarifies the ZIP constraint, adding meaning beyond the schema's property descriptions.

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 specifies exact accepted input formats (GPX/FIT/CRSProf URL, ZIP with one GPX, artifact, raw JSON, inline course_file) and states the destination ('into a CRSProf artifact'), clearly distinguishing from siblings like enrich_course_waypoints via the 'before waypoint enrichment' cue.

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?

Explicitly states usage timing ('Use this on catalog misses before waypoint enrichment') and gives a clear when-to-alternative: if URL blocked, use POST /api/artifact-uploads and pass artifact id. This tells the agent when to invoke and what to do instead.

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

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

With no annotations provided, the description must disclose behavior itself. It clearly states the search action and the return of direct URLs, which implies a read-only operation. It goes beyond a tautology by explaining the result's utility. While it doesn't mention potential limits or rate limits, the core behavior is transparent enough for a search 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 a single, front-loaded sentence that efficiently captures the purpose, resource, and output. Every part contributes meaning, with no 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?

This is a simple search tool with a small input schema, a clear output schema, and no complex side effects. The description covers the essential purpose and the downstream use of the returned URLs. The presence of an output schema means the return structure is already documented, so the description does not need to elaborate further.

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 already provides 100% coverage of both parameters: 'query' (the search term) and 'limit' (maximum matches). The description adds no further parameter details beyond what the schema already explains, so 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 description clearly states the verb 'Search' plus the resource 'CourseProfiler's race catalog', and specifies the output ('direct CRSProf URLs') and its purpose ('used as course sources'). This distinguishes it from all sibling tools, which are creation, validation, or import tools rather than search 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 implies when to use the tool: when you need to look up a race/course by name and obtain its CRSProf URL for use as a course source. It gives clear context but does not explicitly state when not to use it or mention alternatives, though no direct alternative search tool exists among the siblings.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure and does so excellently. It reveals that a final CRSProf artifact is not a submission, that absence of submission_id indicates no submission, that blocked route links should trigger a user upload request, that conflicting waypoints require user confirmation, and that unconfirmed fields must be omitted rather than guessed. It also discloses return value semantics (job with submission_id and final_crsprof_artifact_id). These are critical behaviors beyond a simple 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?

Despite its length, the description is well-structured and front-loaded. The first sentence states the core purpose, followed by sibling differentiation, usage rules, metadata instructions, and exclusions. Each section addresses a distinct need, and the verbose metadata guidance is justified by the tool's complexity. No sentence is wasted; the length is appropriate for the number of edge cases covered.

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 is remarkably complete given the tool's complexity. It covers prerequisites (searching the catalog, official sources), the full pipeline, accepted source formats, blocked-link fallback, conflict resolution, return value semantics, and explicit don'ts. With a rich output schema presumably present, the description still adds necessary context about job progress and artifacts, ensuring the agent understands the entire submission workflow.

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 only 50%, but the description compensates extensively. It provides concrete examples for metadata.event.name vs course ('name='Speedgoat Mountain Races', course='50K''), explicitly warns against putting distance/elevation in the course name, clarifies that location must not include country, and enumerates required event link types. It adds practical field-level guidance that is absent from the schema, greatly enhancing parameter understanding.

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 clear statement: 'Submit an official/trusted course for CourseProfiler catalog review.' It immediately distinguishes itself as 'the only MCP tool that creates a catalog-review submission' and names sibling tools (import_course, enrich_course_waypoints, generate_course_segments, create_race_plan) that do not fulfill this purpose. The verb 'submit' and resource 'course for catalog review' are specific and 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 explicit when-to-use guidance: 'Use this only when the user asked to submit/add/update a course in the catalog.' It also provides a strong exclusion: 'Do not call submit_course for normal race-plan creation; create_race_plan does not require catalog submission.' It further details a pipeline order ('Use this after discovering the official route source externally, importing... enriching... applying metadata, and generating segments') and warns against submitting synthetic geometry, making the usage scope very clear.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior. It clearly states the tool is non-mutating and does not submit courses, which are key behavioral traits. It does not mention specific validation checks or error reporting, but the existence of an output schema helps cover return values. Overall, the transparency is good for a validation 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 two sentences, front-loaded with the core action and context, followed by a concise clarification of non-mutation. There is no wasted phrasing, and it fully earns its 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?

The description covers the tool's purpose, input modes, and non-mutating nature. Given that an output schema exists, it does not need to explain return values. The main gap is the lack of explicit statement about parameter exclusivity and what validation actually checks, but for a tool of this complexity, the description is reasonably 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 has 50% description coverage (crsprof_artifact_id has a description, crsprof does not). The description compensates by clarifying 'inline CRSProf JSON' for the crsprof parameter and 'artifact ID' for the crsprof_artifact_id parameter, and by indicating these are alternate inputs ('or'). This goes beyond the schema, though it stops short of explicitly stating whether both can be provided simultaneously or are mutually exclusive.

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 verb 'validate', the resource 'CRSProf artifact or inline CRSProf JSON', and the context 'before race planning or catalog submission'. It also distinguishes from sibling tools by explicitly noting it does not mutate artifacts or submit courses, making its 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 explicit timing guidance ('before race planning or catalog submission') and clarifies what it does not do ('does not mutate artifacts or submit courses'), which implies when not to use it. However, it does not explicitly name alternative tools (e.g., submit_course) or mention that only one of the two input modes should be provided, which would strengthen the guidance.

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

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

With no annotations, the description carries the full burden. It explicitly discloses that the tool does not mutate artifacts or generate a new profile, which is the key behavioral trait for a validation tool. However, it does not mention what happens on invalid input or whether there are other side effects, leaving some gaps.

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 sentences, front-loaded with the primary purpose and followed by a concise behavioral disclaimer. Every piece of text adds value with no redundancy or fluff.

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?

Despite having no annotations, the description covers purpose, usage timing, and side-effect boundaries. The output schema covers return values, and the two parameters are effectively explained. For a validation tool with this simplicity, the description is complete enough to guide 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?

The description maps 'USRProf artifact or inline USRProf JSON' to the two parameters: usrprof_artifact_id and usrprof. This compensates for the schema's missing description on usrprof and clarifies the 'or' relationship. Still, it does not explicitly state whether exactly one must be provided or both are allowed, which could be ambiguous given the schema has no required fields.

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 verb 'Validate' and the resource 'USRProf artifact or inline USRProf JSON', and includes the context 'before creating personalized race plans'. This distinguishes it from sibling tools like validate_course_profile and generate_runner_profile.

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 gives clear context on when to use ('before creating personalized race plans') and states a when-not boundary ('This does not mutate artifacts or generate a new profile'). However, it does not explicitly name alternative tools for mutation or generation, stopping short of full alternative guidance.

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