ourpr courses

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, fully covering the safety profile. The description adds no extra behavioral context such as performance characteristics, permissions, or data implications. Since it does not contradict the annotations, a 3 is appropriate given the annotation coverage.

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, tightly written sentence: 'Whether one particular run was an interval session, and its reps.' It immediately states the purpose with zero waste, front-loading the core functionality. This is exemplary 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?

With one parameter, a documented schema, an output schema, and rich annotations, the description is sufficient for an agent to call the tool correctly. It explains the purpose clearly, and the output schema presumably covers return details. It could add a note on what 'reps' specifically include, but this is a minor gap given the other structured information available.

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%, and the single parameter activity_id is well described as 'Run id from ourpr_list_runs.' The tool description adds no additional semantic detail beyond the schema, so it relies entirely on the schema's documentation. This meets the baseline for high schema coverage.

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: determining whether a specific run was an interval session and retrieving its reps. It uses a specific verb ('look for'/'detect') and resource (reps in a single run), and differentiates from siblings by focusing on a single run rather than list or general run tools. However, it does not explicitly name alternative tools, so it falls just short of a 5.

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 when you have a specific run ID and want to know if it was intervals, but it provides no explicit guidance on when to prefer this tool over siblings like ourpr_rep_workouts or ourpr_run_laps. There is no mention of alternatives or exclusions, leaving the agent to infer from the stated purpose.

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?

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds substantial context beyond that: why fields are omitted (83 KB payload, 91% profile), the deliberate reporting of both distance_mi and measured_mi without reconciliation, and the slug-unknown error 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 main purpose and exclusions are front-loaded in the first sentences, and the detailed Returns block is justified for a data-rich tool. However, the block is quite long and includes many inline comments that could be trimmed slightly without losing 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?

For a read-only, idempotent tool with an output schema, the description is complete: it gives examples, error handling, sibling routing, field semantics, and format guidance. Nothing an agent needs to select and invoke it correctly is missing.

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%, so both parameters are already fully documented. The description adds useful context like the slug source ('From ourpr_list_courses') and the purpose of response_format, but this is incremental rather than essential.

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: 'Read one published course' and then enumerates exactly the fields it returns. It explicitly distinguishes itself from siblings by stating it is deliberately without elevation profile, amenities, and centerline, and that those are separate 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 provides clear usage context with examples and an explicit 'Do not use when' for terrain, naming ourpr_get_course_terrain as the alternative. It notes that amenities and route data live in 'three more tools' but does not name those specific sibling tools, so routing is not fully comprehensive.

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?

Beyond the readOnly and idempotent annotations, the description discloses critical behavioral nuances: the data source is OpenStreetMap, mapped taps may be seasonal/shut off/gone, and empty arrays mean 'none mapped' not 'none exist.' This adds essential interpretive guardrails that the annotations alone do not convey, and there is no contradiction with the readOnlyHint.

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 well-structured with clear sections (overview, limitations, args, returns, examples, error handling) and front-loads the core purpose. While it is longer than average, every sentence earns its place by addressing a specific concern or clarifying usage. The formatting aids scanability despite the 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?

With an output schema present, the description focuses on higher-level context: it explains the limitations, the training-use case, the 'Do not use' condition, and the meaning of empty results. Combined with the output schema and annotations, an agent has all necessary information to invoke this tool correctly and interpret its results. Nothing critical is missing.

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 baseline is 3. The description adds value by specifying the slug should come from ourpr_list_courses and clarifying the response_format semantics ('markdown reads well in a chat answer, json carries every field for further computation'). This extra context makes the parameters more actionable than the schema alone, justifying a 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 clearly states the tool's function: returning public drinking water and toilets on a course, positioned by mile. It explicitly differentiates from race-day aid stations, which distinguishes it from sibling tools like ourpr_get_course_route or ourpr_get_course_terrain. The title and verb align perfectly with the detailed purpose.

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 this tool ('if I run this course on an ordinary day, where can I drink?') and when not to ('Do not use when: you want race-day aid stations'). It also provides two concrete examples that map natural language queries to intended use, leaving no ambiguity about the selection context.

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?

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds that the GPX file is free and requires no account, and notes that on out-and-back courses start and finish coincide. It also discloses error behavior (returns slug list on unknown slug). These are valuable behavioral details beyond annotations, though rate limits are not mentioned.

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 well-organized with sections for purpose, args, returns, examples, and error handling. Every sentence adds value, from the GPX note to the out-and-back edge case. It is efficient and front-loaded with the core purpose.

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 includes an inline return schema, examples, error handling, and an edge case. For a read-only tool with three parameters and annotations covering safety, this is comprehensive. An agent has everything needed to call it correctly.

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 baseline is 3, but the description adds provenance for slug ('From ourpr_list_courses') and clarifies the polyline's size and when to use it. The response_format guidance (markdown for chat, json for computation) adds meaning beyond the enum definition.

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 precise statement of what the tool returns: start, finish, bounding box, mile markers, and streets in order. This clearly identifies the course route as the resource and distinguishes it from sibling tools like amenities or terrain. The title 'Get a course's line' reinforces the purpose.

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 includes concrete examples mapping natural-language queries to output fields (e.g., 'Send me the Boston course for my watch' -> gpx_url). However, it does not explicitly contrast this tool with siblings like ourpr_get_course_amenities or ourpr_get_course_terrain, leaving routing to inference. The examples provide useful context but lack explicit exclusions.

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?

Annotations already declare read-only and idempotent behavior; the description goes much further by disclosing the USGS 3DEP 10m data source rather than barometer data, explaining that sampled extremes are always retained, and clarifying that an empty named_sections array does not mean a course is flat. Error handling behavior is also disclosed, and nothing contradicts the annotations.

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 definition is well-structured with clear headers, examples, and error handling, and the core purpose is front-loaded. It is slightly padded by an Args section and a Returns block that largely restate the schema, but overall the organization keeps it scannable and purposeful.

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 tool with this parameter count, output schema, and annotations, the description covers all operational context: data source, sampling behavior, edge-case semantics, error handling, and example invocations. Nothing needed to call it correctly is missing.

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?

Slug semantics are enriched with provenance ('From ourpr_list_courses') and example queries map directly to concrete slug values. Points and response_format are already thoroughly documented in the schema, so the description adds modest but real value beyond the schema's 100% coverage.

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 precise statement: it returns the sampled elevation profile of one course plus named climbs and descents. The bold claim 'THIS IS THE TOOL FOR "what are the hills and where"' anchors its unique role and clearly separates it from course-detail or route siblings. Title and description agree and reinforce each other.

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 tool is explicitly framed as the one to answer hill-related questions, with natural-language examples mapping queries to slugs and a note to read climb_ft_per_mi for flatness. It does not name sibling tools like ourpr_get_course or ourpr_similar_terrain or state when not to use it, so the guidance is clear but not exhaustive.

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?

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description does not need to repeat that. It adds value by enumerating the return contents (mile splits, heart rate, cadence, calories, device), which tells the agent what behavioral payload to expect beyond the 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?

Three short sentences deliver the core content first, then the ID source, then the alternative tool. There is no filler or repetition of annotation/schema details. Every sentence 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?

For a single-parameter read-only tool with a full output schema and rich annotations, the description covers everything an agent needs: what data is returned, where the ID comes from, and when to choose a different tool. It is complete for this complexity level.

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 already describes activity_id as 'Run id from ourpr_list_runs,' and the description reinforces the same provenance, which is helpful. Since schema coverage is 100%, the baseline is 3; the description adds a small but meaningful amount by tying the ID to a specific listing tool, nudging it to 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 begins with a specific verb and resource: "One activity in full," and enumerates the precise contents (mile splits, heart rate, cadence, calories, device). It also differentiates itself from the sibling ourpr_run_stream by explicitly pointing there for route profile data, so an agent can distinguish it from other run-related 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 states the source of the required ID ('Id comes from ourpr_list_runs'), telling the agent the prerequisite call. It also provides an explicit alternative: 'For the profile along the route, use ourpr_run_stream.' This is clear when-to-use and when-not-to-use 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context beyond annotations: it clarifies that total_mi is the whole network, not a single runnable distance, and it explains the error behavior for unknown slugs. It doesn't mention rate limits or pagination, but those are not relevant for a single-resource read 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 well-structured and front-loaded: the first sentence states the core purpose, followed by clear Args, Returns, Examples, and Error handling sections. Every section earns its place, and the total length is appropriate for the tool's complexity. The use of a compact JSON return example is 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 tool has a rich output schema, full parameter documentation, and clear annotations. The description adds the missing context: how to get the slug, what the numbers mean, and what happens on error. An agent has everything needed to select and invoke this tool correctly without opening the 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?

Schema coverage is 100%, so the schema already documents both parameters. The description adds value by telling the agent where to obtain the slug (from ourpr_list_trail_systems) and by giving a concrete example. It also explains the practical difference between 'markdown' and 'json' output formats, which goes beyond the schema's enum definition.

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 ('Read') and a clear resource ('one trail system'), then enumerates exactly what data is returned: miles, mapped ways, location, and source. It is easily distinguished from siblings like ourpr_get_course or ourpr_list_trail_systems, which operate on different resources or list multiple items.

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 the agent to get the slug from ourpr_list_trail_systems, provides concrete examples ('How many miles of trail are in Fort Worth?' -> slug='trinity-trails'), and explains when to use the response_format. It also covers error handling by stating that an unknown slug returns a slug list suggestion. This is strong, actionable 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?

Beyond the annotations already signaling a safe read operation, the description discloses meaningful behavioral traits: courses are measured centerlines built from recorded runs, elevation comes from the USGS 3DEP 10 m model, courses are sorted by soonest race date, and 'days_out' becomes null once the date passes. It also exposes the 'No course matched' error 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 core purpose and the most important workflow guidance, and it is well organized into Args, Returns, Examples, and Error handling. However, the Args and Returns blocks partially duplicate the input schema and output schema that are already provided as structured fields, which adds some redundancy and prevents a perfect score.

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 9-parameter tool with no required parameters, the description covers entry-point usage, parameter semantics, default values, result ordering, error handling, and when to route to a sibling tool. Nothing an agent needs to correctly select and invoke this tool appears to be missing.

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%, so the baseline is 3, but the description adds value through natural-language usage examples ('What marathons does ourpr. have?' -> min_distance_mi=26) and by restating defaults in a compact, readable form. It mostly repeats the schema, but the examples and 'upcoming_only' semantics improve parameter understanding 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 first sentence names a specific verb ('List'), a specific resource ('every running course published on ourpr.'), and the core returned attributes: place, distance, climb, and next race date. It also clarifies that this tool is the source of slugs for every other course tool, distinguishing it from siblings like ourpr_get_course and ourpr_get_course_terrain.

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 explicitly says 'START HERE' and explains that every other course tool takes a slug, which is where slugs come from. It also gives a clear when-not-to-use rule: 'when you want the hills on one course. Use ourpr_get_course_terrain.' The worked examples map natural language requests to concrete parameter values.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: the output reveals whether a logged run fulfilled a plan and whether 'ourpr.create' wrote it, and it warns about collision checking before planning.

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 focused sentences: the first states the core purpose and output contents, the second gives the critical usage instruction. No filler or redundant restatement of the schema.

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?

With a rich output schema, full parameter documentation, and strong annotations, the description covers the remaining essential context: what the response contains and why the agent should call it before planning. Nothing important is missing for 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?

Schema description coverage is 100%, and both start_date and end_date already explain format and default behavior. The tool description does not need to repeat parameter details; it adds no additional parameter semantics, so the baseline of 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 uses a specific verb ('List') with a precise resource ('the runner's planned runs') bounded by a date window, and enumerates the returned fields (day, name, miles, time, tag, note, fulfillment status, source). This clearly distinguishes it from sibling tools like ourpr_list_runs, which covers logged runs.

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 explicitly tells the agent to read this tool before ourpr_plan_week to avoid placing a new plan on a day that already has one. That is concrete, actionable guidance tied to a real pre-condition, going beyond general context.

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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the description only needs to add context beyond safety. It adds ordering behavior ('newest first'), the inclusion of tune-ups, the returned fields, and the secondary fastest-result summary.

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 the core scope and ordering, followed by concrete output fields and the additional fastest-results behavior. Every clause adds useful information and there is no filler.

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 read-only list tool with an output schema and strong annotations, the description is nearly complete. The only mild gap is that it does not clarify how the distance filter interacts with the 'fastest result at 5K, 10K, half marathon and marathon' summary, which could be ambiguous when a distance filter is applied.

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%: limit has a clear 'Most rows to return' description and distance has 'Only races at this distance.' The tool description adds no additional semantics for these parameters, which is acceptable given the schema already carries the burden.

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 states a specific verb and resource: 'Every race... in the history, newest first, tune-ups included', and enumerates the returned fields. This clearly separates it from sibling list tools like list_runs or list_courses.

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 clear context for when to use this tool: when an agent needs race history, including tune-ups, with fastest-result summaries. It does not explicitly name alternative sibling tools or exclusions, but the scope 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by specifying the result ordering ('newest first'), the date-range scope, and the output fields, which goes beyond the structured annotations.

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 compact sentences put the essential output and ordering first, then state the intended use and the sibling tool for splits. There is no filler 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?

With rich annotations, a complete input schema, and an output schema present, the description provides the missing context: scope, ordering, and how this tool fits into the run-history workflow. Nothing essential is absent for an agent to select and invoke it correctly.

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%, and the schema documents all four parameters with defaults, bounds, and examples. The description adds only a general 'between two dates' hint, so the schema carries the parameter-documentation burden as expected.

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 verb and resource ('Training history between two dates'), enumerates the returned fields, and differentiates itself from the sibling ourpr_get_run by framing itself as the starting point for totals/streaks/trends. It is immediately clear what the tool does and how it differs from run-detail 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?

It explicitly says 'Start here for totals, streaks, trends, or finding a run' and routes split-level analysis to 'ourpr_get_run with an id from here.' This gives the agent a clear when-to-use and a named alternative, leaving little ambiguity.

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?

Annotations already declare readOnly, idempotent, and non-destructive behavior, lowering the bar. The description adds value by clarifying the domain-specific meaning of 'trail system' and stating the return shape (count and array). It does not contradict annotations, though it repeats some schema 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 well-structured: a clear purpose sentence, then Args, Returns, Examples, and a 'Do not use when' note. It is front-loaded and each section earns its place, though the return schema partially duplicates the output schema.

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 tool with one optional parameter, an output schema, and strong readOnly/idempotent annotations, the description fully covers purpose, usage, disambiguation, and return semantics. Nothing an agent needs to call it correctly is missing.

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% and the single parameter response_format is fully documented in the schema with enum and default. The description only restates the default and adds a practical note about markdown vs json, which is marginal. 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 opens with a precise verb ('List') and a scoped resource ('every trail system'), and immediately differentiates from single routes by defining a trail system as a network of connected paths. This distinguishes it from sibling ourpr_list_courses without ambiguity.

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 usage examples and includes a 'Do not use when' clause pointing to ourpr_list_courses with kind='trail' for single measured routes. This clearly routes the agent to the correct sibling in the ambiguous case.

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?

Annotations already indicate a write operation (readOnlyHint=false), non-idempotency, and non-destructiveness. The description adds value by specifying that plans are visible, editable, and removable, and that a token with 'write scope and ourpr. create' is needed. It also clarifies it does not log runs. However, it doesn't elaborate on behavior when plans already exist on the same date or on rate limits, which would further improve 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?

Four sentences, each carrying essential information: the primary action, the outcome, the authentication requirement, and an explicit exclusion. The description is front-loaded with the purpose and avoids any 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?

For a tool that writes up to 14 plans with multiple fields, the description covers the core behavior, token requirement, and non-logging nature. It doesn't mention whether existing plans on the same date are replaced or appended, which could be relevant, but given the output schema is present (per context signals) and the schema already validates dates, the description is 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?

The schema covers 100% of the parameter descriptions, so the baseline is 3. The description only loosely references the array ('one planned run, or a week of them') and doesn't add syntax or format details beyond the schema. It provides minor context that these are plans rather than logs, but overall the schema does the heavy lifting.

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 states a specific verb ('write') and resource ('planned run(s)') onto 'days still ahead', which clearly distinguishes it from the read-only sibling tools like ourpr_list_plans and ourpr_get_run. It also explains the result ('a plan they can see, edit and remove'), making the tool's 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 clear context for when to use the tool (to put planned runs on the runner's week) and explicitly notes it 'Never logs a run', which implies a separate tool handles logging. It also states the required token scope ('write scope and ourpr. create'), which is a prerequisite. It doesn't name an alternative tool, but no sibling performs a similar write action, so this is sufficient.

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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context by warning that detection is conservative, which complements the openWorldHint and helps the agent calibrate expectations about completeness.

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 the core purpose, and no filler. The cautious-detection caveat and the fallback to ourpr_list_runs are placed exactly where they add decision 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?

With one optional parameter, strong safety annotations, an output schema, and a clear detection-behavior caveat, nothing essential is missing for an agent to select and call this tool correctly.

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 single 'limit' parameter is fully documented in the schema. The description adds no extra parameter semantics, which is fine because the schema already carries the burden.

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 states a specific verb and resource ('Interval sessions found across the history') and adds the concrete payload ('with reps and distances'). It also differentiates itself from ourpr_list_runs by noting this tool only contains detected interval sessions, so an agent can tell what it returns.

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 clear practical guidance: detection is conservative, and any missed session is still available in ourpr_list_runs. This effectively names a fallback alternative, though it does not explicitly cover when to prefer this over the closely related sibling ourpr_detect_reps.

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?

Annotations already cover the read-only and idempotent nature of the operation, so the description does not need to establish safety. It adds useful behavioral context by explaining that laps are manually recorded button presses and that lap boundaries follow the workout rather than mile markers.

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 short sentences with no filler. The core definition is front-loaded, and the second sentence earns its place by distinguishing laps from mile splits, though it is slightly more poetic than necessary.

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 getter with one fully described parameter, robust read-only annotations, and an output schema, the description covers everything needed to select and call the tool. No prerequisites, side effects, or return-value details are missing.

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 fully documents the single required parameter activity_id and even states it comes from ourpr_list_runs. The description adds no parameter-specific detail, so with 100% schema coverage 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 title and description clearly identify the resource as the watch-recorded laps for a single run, with the clarifying phrase "runner's own button presses." It distinguishes manual laps from mile splits, though it does not explicitly name a sibling tool to differentiate against.

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 the agent needs manual button-press laps rather than mile splits. However, it never explicitly states when to choose this tool over siblings like ourpr_get_run or ourpr_run_stream, leaving some routing to inference.

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?

Annotations already declare the operation read-only, idempotent, and non-destructive. The description adds meaningful behavioral context beyond those annotations: data is aggregated on a 10 m grid, only min/avg/max/coverage are returned rather than every sample, and an indoor run may legitimately yield no profile.

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 filler. The first sentence front-loads the core behavior (grid, channels, aggregations) and the second adds a critical edge case, all without 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 one-parameter tool with annotations covering safety and an output schema present, the description is complete. It explains what is returned, how it is structured, and the key exceptional case (indoor runs), so an agent can select and invoke it correctly.

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?

There is only one parameter, activity_id, and the schema already documents it as a run id from ourpr_list_runs. The description adds no extra parameter-level detail, but because schema coverage is 100%, the baseline 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 title and description clearly identify the tool as returning a run's elevation and sensor profile aggregated on a 10 m grid. It specifies the exact channels (elevation, heart rate, power, cadence) and the aggregation dimensions (min, average, max, coverage), which distinguishes it from sibling tools like ourpr_get_run or ourpr_run_laps.

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 an aggregated, gridded sensor/elevation profile is needed for a run. It also gives a useful exclusion—indoor runs normally have no profile—but it does not explicitly name alternatives or state when a sibling tool should be preferred.

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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds purpose context but no additional behavioral details such as return format, pagination, or empty-result handling. No contradiction with annotations.

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, compact sentence that front-loads the core function ('Stretches of past runs matching a distance and climb') before the explanatory clause. There is no redundant phrasing.

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?

With an output schema present, the description need not detail return values. It gives enough to understand the tool's intent, but it lacks guidance on typical use cases (e.g., race preparation) or any limitations. Adequate but not rich for a 4-parameter 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 100%, with every parameter (miles, gain_ft, limit, tolerance_ft) having a clear description. The tool description adds no parameter-level information beyond what the schema provides, so the 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 resource ('past runs') and the purpose ('matching a distance and climb'), with an illustrative note about race training. It is specific and not a tautology, but it does not differentiate from sibling tools like ourpr_run_laps or ourpr_run_stream.

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 explicit guidance is given on when to use this tool versus alternatives. The race-training phrase implies a use case, but no exclusions or alternative tool references are provided, leaving the agent to infer 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds useful behavioral context by explaining the data returned, the concept of a Block, and that it computes which week of the Block today falls in. This goes beyond the annotations without contradicting them.

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, front-loads the primary subject, and defines the key domain term 'Block' at the end. Every sentence adds value and there is no redundant or filler 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?

The description plus the output schema and annotations cover the essential information an agent needs: what data is returned, what a Block is, and how the past parameter behaves. It does not discuss edge cases like no past races or timezone handling for 'today', but these are minor for a read-only, idempotent retrieval tool with a well-documented 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?

The single parameter 'past' is fully documented in the schema with description, default, and bounds. The description adds some related context by mentioning past race Blocks, but does not directly explain the parameter semantics beyond what the schema already provides. This matches the baseline for full schema coverage.

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 a specific resource ('goal race and training blocks') and enumerates exactly what is returned: race day, distance, goal time, current week, weekly miles, and past race blocks with results. This distinguishes it from sibling tools like ourpr_list_races or ourpr_plan_week, which cover different aspects of race/plan data.

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 makes the intended use obvious by naming the goal race and training block context. It does not explicitly mention when not to use it or name alternatives, but the content is specific enough that an agent can infer when this tool is appropriate. No misleading guidance is present.

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