CourseProfiler

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 thoroughly discloses behaviors: the tool creates a plan/PDF, does not submit to the catalog, requires course and runner input, and details what to do if data is missing. It warns about third-party host blocks and cautions against inventing data, providing complete transparency.

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 very long and covers many edge cases. While the first sentence front-loads the purpose, the extensive detail makes it less concise. It could be structured more clearly with bullet points or sections to improve readability 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 (7 parameters, nested objects, many sibling tools), the description is exceptionally complete. It covers prerequisites, workflow sequencing, error handling (e.g., blocked URLs), and references to other tools. The output schema exists, and the description notes it returns a top-level job with artifact role metadata, which is sufficient.

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 low (43%), so the description must compensate. While the description does not repeat parameter descriptions, it adds substantial context for fields like course.source and runner.sources, explaining when to use artifact_id vs. source, and how to handle file uploads. This adds meaning beyond the schema, though it could be more concise.

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 it is the primary tool for creating a personalized race plan and optional PDF. It distinguishes from siblings by specifying prerequisites (course and runner input) and clarifying it does not submit to the catalog. The verb 'create' and resource 'race plan' 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 provides extensive guidance on when to use this tool versus alternatives. It explicitly states to use after obtaining course and runner input, and specifies when to call sibling tools like search_race_catalog, import_course, enrich_course_waypoints, generate_course_segments, and submit_course. It also gives clear exclusions, such as not creating a plan without a real route file and not inventing missing data.

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 provided, so description carries full burden. Discloses important behaviors: unsupported resources are ignored with warnings, preference for structured mode, and merging strategy. 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?

Description is well-structured and front-loaded with main action. Each sentence adds value, though slightly verbose with implementation details. Still efficient for the complexity.

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?

Tool has nested objects and output schema; description covers purpose, usage, and behavior adequately. No gaps given the context signals.

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 50%, but description adds value by reinforcing mode preference and caution about table_url. It provides guidance beyond schema, though some parameter details are left to 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?

Description clearly states the tool adds structured waypoints to a CRSProf artifact, distinguishing it from sibling tools like import_course which creates artifacts. It also specifies handling of existing waypoints.

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 guidance: inspect for existing waypoints to avoid duplicates, prefer merging/updating, and label route-only plans as incomplete unless official waypoints are present. This helps the agent decide when and how to use.

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 only mentions the tool's input sources and output destination but does not disclose side effects, required permissions, idempotency, rate limits, or error behavior. Essential behavioral traits are missing.

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 with no wasted words. The first sentence states the core purpose and conditions, the second clarifies a critical distinction. Information is front-loaded and every sentence adds value.

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 (2 parameters, nested object, output schema exists), the description covers the tool's role in a pipeline, prerequisites (enriched CRSProf or catalog CRSProf), and post-processing steps. It lacks explicit mention of error cases or validation requirements but is largely complete for an experienced 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 description adds context beyond the schema by explaining the crsprof_artifact_id parameter can come from two sources (enriched CRSProf or catalog CRSProf). The schema itself describes most sub-properties of options, but the description adds meaning about the parameter's origin and downstream use.

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 generates analytical course segments from two specific sources (enriched CRSProf after waypoint enrichment or catalog CRSProf with official data). It uses specific verb 'generate' and resource 'course segments', and distinguishes from siblings by mentioning downstream usage with create_race_plan and submit_course.

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 explicitly provides when to use this tool (after waypoint enrichment or from catalog CRSProf) and what to do with the result (use in create_race_plan or submit_course if user asked). It also states a clear exclusion: 'A generated CRSProf artifact is not a catalog submission.'

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 present, so the description carries the full burden. It reveals that the download URL is 'short-lived', which is a behavioral trait beyond the schema. However, it does not mention other important traits like read-only behavior, authentication needs, or rate limits. The description is adequate but not comprehensive.

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, front-loaded with the verb and resource. Every word is necessary; no waste. Excellent conciseness.

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 presence of an output schema and a single, fully described parameter, the description is adequate for a simple fetch operation. However, it lacks usage context, behavioral details (no annotations), and does not mention prerequisites or limitations. Completeness is moderate.

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 covers 100% of the parameter (artifact_id), so the description adds minimal meaning beyond the schema. It simply states 'by artifact_id', which restates the schema's purpose. Baseline 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 ('Fetch') and the resource ('artifact metadata and a private short-lived download URL') with the condition 'by artifact_id'. It is specific and distinct from sibling tools like 'get_artifact_upload_requirements' through the name, but the description does not explicitly compare to alternatives.

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?

There is no guidance on when to use this tool versus its siblings, such as when to use 'get_artifact' vs 'get_artifact_upload_requirements'. The description only states what it does, not the context or prerequisites.

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, description carries full burden. It discloses it is an instruction helper and not a raw-byte tool, but does not detail what the instructions entail or if there are side effects. Adequate but not exhaustive.

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, front-loaded with purpose and usage, no extraneous content.

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 zero parameters and an output schema, the description sufficiently covers the tool's role as an instruction helper; return values are explained by schema.

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?

Input schema has 0 parameters, so baseline is 4. Description does not need to add parameter info; schema coverage is 100%.

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 provides instructions for CourseProfiler's REST artifact upload flow and explains limitations of hosted MCP, distinguishing it from a raw-byte upload tool.

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 says 'Use this when an assistant needs instructions... or needs to explain why...' and clarifies it is an instruction helper, providing clear context for when and when not to use.

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 what the tool returns (workflow, route sources, etc.), which implies a read-only operation. However, it does not explicitly state behavioral traits like side effects, auth requirements, or error handling. The description is adequate but lacks full transparency.

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 long. The first sentence states when to use the tool, and the second lists what it returns. No unnecessary words, highly 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?

Given the tool has 3 optional parameters, an output schema, and no required fields, the description is sufficiently complete. It covers when to use and what to expect. Only minor gaps in behavioral details prevent a perfect score.

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 has 100% description coverage, so the baseline is 3. The description adds minimal extra meaning beyond the schema, only hinting at the context for 'race_name' by tying it to 'incomplete inputs.' No additional detail is provided for 'known_course_url' or 'has_waypoint_data.'

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 what the tool does: 'Returns the catalog-first course submission workflow, accepted route sources, metadata, waypoint enrichment, and upload requirements.' It also differentiates itself from siblings by explicitly mentioning 'Use this before submit_course' and 'when the user gives only a race name or incomplete inputs.'

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 explicitly tells when to use the tool: 'Use this before submit_course when the user gives only a race name or incomplete inputs.' It provides clear context for usage, though it does not explicitly state when not to use it or mention alternatives.

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 fully disclose behavior. It states 'poll' implying a safe, read-only action, but does not explicitly confirm no side effects, mention authentication requirements, rate limits, or error handling (e.g., what if job_id is invalid). The minimal description leaves behavioral aspects ambiguous.

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, well-formed sentence that conveys the essential purpose without unnecessary words. It is front-loaded with the action and resource, making it easy to parse quickly.

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, no nested objects, output schema exists), the description is largely adequate. It covers the basic operation. However, it could be improved by noting common usage patterns, such as that polling returns a status that may indicate completion or failure, but the output schema likely handles that. Still, minor gap.

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 has 100% coverage, describing job_id as 'CourseProfiler job ID, e.g. job_...'. The description adds no new semantic information beyond restating the parameter's role in polling. Since schema coverage is high, a score 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 purpose: to poll a CourseProfiler async job by job_id. The verb 'poll' indicates checking status, and the resource is a specific job. It distinguishes from siblings like get_artifact and get_race_plan_requirements which target different resources.

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?

No guidance is provided on when to use this tool versus alternatives. For instance, it does not explain when polling is appropriate, what distinguishes it from waiting for job completion, or mention any prerequisites or conditions. The description lacks context on usage.

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 provided. The description explains it returns required inputs and next steps, but does not disclose behavioral traits like idempotency, side effects, or auth needs. It is not contradictory, but could be more informative.

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, no redundancy, front-loaded with key usage instruction. Every sentence adds value.

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 presence of an output schema and the tool's simplicity (3 optional params), the description is sufficiently complete. It explains the return value and eligibility for use. Minor improvement would be specifying the output structure explicitly.

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%, so the parameters are fully described. The description adds context about use case but does not provide additional meaning for individual parameters beyond 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?

The description clearly states the tool's purpose: 'Use this before create_race_plan' and specifies the use case (incomplete inputs). It distinguishes from sibling tools by naming create_race_plan.

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 says when to use ('before create_race_plan', 'when user gives only a race name or incomplete inputs'), but does not explicitly state when not to use it. Alternatives are implied but not named.

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 of behavioral disclosure. It describes what the tool does (provides explanatory guidance on runner input) without hiding any major traits. It does not mention side effects or safety, but as a read-only informational tool, that is acceptable. The description adds value beyond the name by specifying the content of the explanation.

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 exceptionally concise, consisting of two sentences that front-load the use case. Every word serves a purpose, with no fluff or repetition. It efficiently conveys the tool's role and the scope of information it provides.

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 (zero parameters) and the presence of an output schema, the description is largely complete. It covers the key aspects of what the tool explains. However, it could be slightly improved by explicitly stating that the return value is a structured set of requirements, though the output schema likely covers that.

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, so the baseline score is 4 per the calibration rules. The schema coverage is 100% (no parameters to document), and the description does not need to add parameter information. It appropriately focuses on the tool's output and usage.

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 purpose: it explains how to obtain or generate runner input, what files should contain, and how to upload artifacts. The trigger condition 'Use this when runner input is missing or unclear' provides a specific use case, and it distinguishes from sibling tools like get_race_plan_requirements by focusing on runner profiles.

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 explicitly says when to use the tool (when runner input is missing or unclear), providing clear context. It does not explicitly state when not to use it or mention alternatives, but the condition alone is sufficient for most agents. The sibling tool names imply differentiation.

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 provided, so description carries full burden. It discloses important behaviors: third-party hosts may return 403, ZIP accepted only with exactly one GPX, and advises against synthesizing geometry from roadbooks. Could mention success/failure outcomes but still strong.

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?

Description is somewhat verbose but structured with key information front-loaded. Could be more concise without losing essential details. Still effective.

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 (3 parameters with nested objects) and presence of output schema, the description covers main use cases and edge cases (403, ZIP constraints). Room for minor improvements like expected output, but largely 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 description coverage is low (33%). The description explains source types (url, artifact, raw_json, raw_file) and course_file object, but does not detail all properties like options or some source fields. Provides enough context for typical use but leaves some gaps.

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 that the tool imports various course file formats (GPX, FIT, CRSProf, ZIP) into a CRSProf artifact. It distinguishes itself from siblings by specifying its use case: 'Use this on catalog misses before waypoint enrichment.'

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?

Explicit guidance on when to use ('on catalog misses before waypoint enrichment') and when not to (third-party hosts blocking, e.g., Wikiloc). Provides alternative workflow: ask user to upload via POST /api/artifact-uploads.

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 must fully disclose behavior. It states the return type (URLs) and search function, but does not mention if results are limited, paginated, or if the tool is read-only. It does not contradict annotations (none present).

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 sentence that immediately conveys the tool's purpose. No redundant information, front-loaded with the key action 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?

Given the tool's simplicity (2 parameters), the description covers the main functionality and return value. The presence of an output schema likely provides additional details, making this sufficient. Could mention the list nature of results.

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 adds context beyond the schema by explaining that the query is a race/course name and that the result is a list of URLs usable as course sources. This helps the agent understand the output's purpose.

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 (Search), the resource (CourseProfiler's race catalog), and the output (direct CRSProf URLs). It effectively distinguishes this tool from siblings like create_race_plan or import_course, which have different purposes.

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 usage for finding course URLs by name, but provides no explicit guidance on when to prefer this tool over alternatives (e.g., when search is needed vs. importing a course). It lacks when-not-to-use instructions.

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 fully carries the behavioral disclosure burden. It explains the return value (a job with submission_id and final_crsprof_artifact_id), reports failure condition (no submission_id means not submitted), and details constraints like blocking on blocked URLs and requirement for official sources.

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 comprehensive and well-structured, starting with core purpose and differentiation, then usage guidelines, then parameter details. It is thorough but moderately lengthy; however, every sentence adds necessary context, so conciseness is appropriate for the complexity.

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 fully complete given the tool's complexity (6 parameters, nested objects). It covers prerequisites, usage conditions, behavioral details, parameter semantics, return values, error handling (e.g., blocked URLs), and references an output schema. No gaps remain.

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?

Given only 50% schema description coverage, the description adds substantial semantic value beyond the schema. It provides detailed guidance on populating metadata fields (e.g., metadata.event.name vs. course, linking types, competition examples) and clarifies source options, compensating for schema gaps.

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 purpose: submit an official/trusted course for catalog review. It explicitly distinguishes from sibling tools (import_course, enrich_course_waypoints, generate_course_segments) by noting they only create temporary artifacts, making the unique role 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?

Provides explicit when-to-use and when-not-to-use guidance, e.g., 'Use this only when the user asked to submit/add/update a course' and 'Do not call submit_course for normal race-plan creation'. Also instructs to search catalog first to avoid duplicates and specifies not to submit synthetic geometry.

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