HAPI Strava MCP Server

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds the 'top 10' result limit, which is useful behavioral context. However, it does not disclose other behavioral traits such as the meaning of min/max category filters or the required bounds parameter.

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 concise and front-loaded, with a single sentence that includes the tool name and a clear return value. There is no fluff or redundant information. While it is under-specified in terms of parameters, that is a completeness issue, not a conciseness issue.

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 4 parameters with no schema descriptions, no output schema, and sibling tools requiring differentiation, the description is insufficient. It lacks any sense of the query structure, optional filters, or how it differs from sibling tools. The description is too minimal to be considered complete for this complexity.

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 0%, so the description must compensate by explaining parameters. It does not: no meaning for bounds, max_cat, min_cat, or activity_type is provided. The phrase 'matching a specified query' is generic and gives no insight into how to construct the query using the parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns the top 10 segments matching a query, providing a specific action and resource. It distinguishes itself from sibling tools like getEffortsBySegmentId by focusing on exploration rather than specific segment details. However, 'specified query' is vague and does not specify what parameters constitute the query.

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. Sibling tools exist for segment efforts, clubs, and gear, but the description offers no comparison or exclusions. The usage context is only implied by the name, not explicitly stated.

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?

The annotations already indicate read-only, but the description adds key behaviors: the authorization requirement, pagination support, and respect for athlete profile visibility. These go beyond the static annotations and help the agent understand data scope and constraints.

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 brief and front-loaded: the first clause gives the purpose, followed by three short sentences on constraints. Every sentence contributes value with no 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?

Given the tool's moderate complexity (3 parameters, no output schema), the description covers purpose, authorization, pagination, and data filtering. Minor gaps include unspecified pagination limits and the meaning of 'recent,' but overall it's fairly self-contained.

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

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

The schema has no descriptions for id, page, or per_page (0% coverage). The description mentions 'specific club' for id and 'Pagination is supported' for page/per_page, providing some semantic context. However, it does not explain parameter formats, defaults, or boundaries, so the compensation is partial.

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: 'Retrieve recent activities from members of a specific club.' The verb 'retrieve' and resource 'activities' are specific, and it distinguishes from sibling tools like getClubById and getClubMembersById.

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 provides explicit context that the authenticated athlete must belong to the club, which is essential for when to use it. It also notes pagination and profile visibility, but it doesn't name alternative tools explicitly, making the guidance contextually 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 declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds only the 'given club' scoping, which is minimal extra behavioral context. 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, efficient sentence that front-loads the action and resource. Every word contributes meaning without unnecessary 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 simple read-only list tool, the description covers the core purpose and return type ('returns a list'). However, with no output schema and unmentioned pagination parameters, it has notable gaps that reduce completeness.

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 0%, so the description must compensate. It mentions 'given club' which maps to the id parameter, but completely ignores the page and per_page parameters, leaving their semantics undocumented.

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' and clearly identifies the resource 'Club Administrators' with the scope 'of a given club.' This distinguishes it from sibling tools like getClubMembersById (members vs administrators) and getClubActivitiesById.

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 context is clear: it returns administrators for a specific club, implying the need for a club ID. However, it does not explicitly mention when to use this over similar tools like getClubMembersById or when not to use it.

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 and destructiveHint=false, establishing this as a safe read operation. The description adds no further behavioral details like return format, not-found handling, or pagination, but for a simple get-by-id tool, the annotation coverage is adequate.

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

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

The description is a single concise sentence (11 words) that front-loads the primary action. Every word contributes to the purpose, with no redundant phrasing or 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 simple one-parameter get-by-id tool, the description covers the core purpose, and the annotations and schema provide basic facts. However, it lacks any differentiation from sibling tools and does not explain when this tool should be preferred over more specific club queries, leaving some contextual ambiguity.

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 0%, so the description must compensate for parameter semantics. It mentions 'using its identifier', which maps to the id parameter, but provides no additional meaning beyond what the parameter name already suggests. No information about type, format, or required status 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 'Returns a given club using its identifier' uses a specific verb (Returns) and resource (club), clearly distinguishing it from sibling tools that return club subresources like activities, members, or admins. It explicitly names the retrieval action and the key identifier.

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 alternatives such as getClubActivitiesById or getClubMembersById. The description does not mention any use cases, exclusions, or selection criteria, leaving the agent to infer appropriateness from the name alone.

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 and destructiveHint=false, so the read-only safety is covered. The description adds no extra behavioral context such as pagination behavior, authentication needs, or return format details, leaving it at the baseline.

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, but it begins by repeating the tool's title ('List Club Members') before adding new information. While concise, the redundancy makes it slightly less efficient 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?

The tool is a simple read-only list operation with no output schema and annotated as safe. The description conveys the primary purpose and differentiates from siblings, but omits parameter semantics and pagination details, leaving gaps for full autonomous 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 0%, and the description does not explain that the required 'id' is the club identifier, nor does it clarify the optional 'page' and 'per_page' parameters. It only vaguely refers to 'a given club', which is insufficient for correct invocation.

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') and resource ('Club Members') and clearly defines the return as 'athletes who are members of a given club.' This distinguishes it from sibling tools like getClubAdminsById and getClubActivitiesById by specifying the member/fan/athlete focus.

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 a use case (listing club members) but does not explicitly state when to prefer this tool over siblings. No exclusion or alternative guidance is provided, though it is reasonably inferable from the wording.

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 declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds the requirement of a subscription and restricts results to the authenticated athlete's efforts, providing useful context on access and data scoping.

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

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

The description is two sentences, front-loaded with the purpose and followed by the subscription requirement. No redundant information or filler; every word contributes.

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 four parameters, no output schema, and no explanation of pagination or date filtering, the description provides only a high-level overview. It misses key usage details an agent needs to invoke the tool correctly, especially since schema coverage is 0%.

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 0%, so the description should explain parameters like per_page, start_date_local, and end_date_local. It only addresses segment_id via 'for a given segment' and leaves the other three parameters undocumented, failing to compensate for the schema's lack of descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists the authenticated athlete's segment efforts for a specific segment. The verb 'List' and resource 'segment efforts' distinguish it from siblings like getSegmentEffortById, which returns a single effort.

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 use for retrieving all efforts for a segment but does not explicitly mention alternatives like getSegmentEffortById for a single effort, or any exclusions. Usage context is implied rather than explicitly stated.

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 and destructiveHint=false, covering the read-only safety. The description adds no behavioral context beyond restating that it returns equipment—no mention of error conditions, availability of the equipment, or relationship to the logged-in athlete. It does not contradict annotations, but adds zero value beyond 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 a single sentence and short, but it redundantly repeats the title 'Get Equipment' before stating the function. This wastes words without adding information. A cleaner structure would drop the prefix and simply say 'Returns an equipment using its identifier.'

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 is a simple getter with one parameter, clear annotations, and no output schema. The description sufficiently conveys purpose and the identifier parameter. Missing details like return format or error behavior are minor and not essential for a basic lookup, so the description is reasonably complete for its simplicity.

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?

With 0% schema description coverage, the description had the burden to explain the 'id' parameter. It merely calls it an 'identifier', which is redundant with the parameter name 'id'. It does not explain what kind of identifier (e.g., string format, where to find it), so the parameter semantics remain minimally defined.

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 ('Returns') and the resource ('an equipment'), specifying the lookup mechanism ('using its identifier'). This distinguishes it from sibling tools focused on clubs, segments, routes, and athletes, making the 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?

Usage is implied by the name and description: it is for retrieving equipment by ID. However, there is no explicit guidance on when to use this tool over alternatives, such as scenarios where an athlete's gear list is needed or how to obtain the ID. For a simple getter, basic implied usage is acceptable but lacks explicit direction.

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

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

Annotations already mark this as a safe read operation. The description adds useful context about scope-dependent response detail (summary vs. detailed), which is not present in the annotations. This goes beyond the bare read-only hint.

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 concise and front-loaded, with no wasted words. Every sentence adds value: the first states the core action, the second adds an important scope-based nuance.

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?

There is no output schema, so the description must convey what the tool returns. It explains that a detailed or summary representation is returned based on scope, which is the key behavior. It could elaborate on what each representation contains, but for a zero-parameter tool, it is adequately 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 tool has zero parameters, so the schema is trivially complete. The description doesn't need to explain parameter semantics, and the baseline for zero parameters is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns the currently authenticated athlete, using a specific verb and resource. It distinguishes itself from sibling tools that target clubs, segments, gear, or routes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context about when to use this tool (to get the authenticated athlete) and even notes that the output representation depends on OAuth scope. It doesn't explicitly name alternatives or exclusions, but the tool's focus is unambiguous 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?

The annotations already declare this as a safe read operation (readOnlyHint=true). The description adds that it returns clubs where the athlete is a member, but it does not disclose pagination behavior or return format beyond 'a list'. This adds some context but misses key behavioral details.

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

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

The description is a single sentence that directly states the tool's function. It is concise, front-loaded with the title, and contains no redundant or excessive wording.

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 is simple with two optional parameters and no output schema. The description covers the main purpose but omits pagination semantics and the nature of the returned list (e.g., that it contains club objects), leaving some gaps for an agent needing to 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?

The schema provides no descriptions for 'page' and 'per_page', and the tool description does not mention them at all. With 0% schema description coverage, the description fails to compensate for the missing parameter semantics, leaving the agent to infer their meaning.

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 lists clubs for the authenticated athlete, using a specific verb (List/Returns) and resource (clubs). It distinguishes itself from sibling tools like getClubById, which target specific clubs.

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 the tool is for retrieving the current user's club memberships and provides clear context from the resource name. However, it does not explicitly mention when to use it versus alternatives or provide exclusions, so it falls slightly short of full 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 and destructiveHint=false. The description adds valuable behavioral context: private segments are filtered out unless the token has read_all scope. This goes beyond the annotations and clarifies an edge case.

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, front-loaded with the core purpose and followed by an important caveat. Every sentence earns its place with no extraneous details.

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

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

Given the tool's simplicity, the description covers the main purpose and a key filtering behavior. However, since there is no output schema and parameters are undocumented, the description is not fully complete; it omits pagination behavior and response structure. Still, for a list operation, it provides adequate context.

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

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

The input schema defines page and per_page as integers without any description, and schema coverage is 0%. The description does not explain these parameters or their behavior (e.g., default values, max per_page, 0-indexing). The description fails to compensate for the lack of schema documentation.

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 the verb 'List' and clearly identifies the resource: 'authenticated athlete's starred segments.' This distinguishes it from sibling tools that deal with clubs, activities, or segment exploration. The additional note about private segments being filtered out adds specificity.

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 does not specify when to use this tool versus alternatives like exploreSegments. It implies usage by describing the authenticated athlete's starred segments, but there is no explicit comparison or exclusion, leaving the agent to infer the appropriate 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 indicate readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: it scopes to the authenticated athlete and discloses private route filtering based on token scope. No contradictions with annotations; the added detail goes beyond the structured fields.

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

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

The description is two sentences, front-loaded with the purpose and followed by a key behavioral note. Every word adds value; no filler or repetition. It is concise and well-structured.

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 list tool with strong annotations, the description covers the essential purpose and an important edge case (private routes). However, it omits any mention of pagination parameters or response structure, and there is no output schema to compensate. Still, it is adequate for basic 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 0%, and the description does not mention the 'page' or 'per_page' parameters at all. The agent is left with no guidance on pagination behavior, defaults, or valid ranges. This is a significant gap since the description must compensate for low schema coverage but fails to do so.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns a list of routes created by the authenticated athlete, using the specific verb 'Returns' and resource 'routes'. It distinguishes from siblings by specifying the authenticated athlete scope and the private route filtering condition, making the 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 provides clear context on when the tool applies (listing authenticated athlete's routes) and clarifies that private routes are excluded unless read_all scope is used. It does not explicitly mention alternatives or when not to use, but the context is sufficient for selection among siblings.

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

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

Annotations already indicate read-only and non-destructive. The description adds useful behavioral context: ownership restriction (only efforts from the authenticated athlete's activities) and the subscription requirement, which are not in 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 description is very concise, with no filler. It front-loads the tool name and provides a direct definition plus one context note (subscription). Every word earns its place.

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

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

For a simple read-only operation with one parameter, the description is adequate but incomplete. It omits parameter semantics and return value details, but annotations cover safety and the sibling list helps context. The subscription requirement is an important addition.

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

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

The schema has 0% description coverage, so the description must explain the 'id' parameter. It does not explicitly state that 'id' refers to the segment effort ID, nor does it clarify the format or required context. This is a significant gap for a single-parameter tool.

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 (returns a segment effort) and resource (segment effort owned by the authenticated athlete). It distinguishes from sibling getEffortsBySegmentId by implying a single effort is returned, though it doesn't explicitly mention 'by ID'.

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 provides a prerequisite ('Requires subscription') but gives no guidance on when to use this vs. alternatives. No explicit exclusions or alternatives are mentioned, though the ownership condition implies it's for the athlete's own efforts.

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 readOnlyHint annotation, the description adds a key behavioral detail: it only includes activities with 'Everyone' visibility. This transparency about data filtering is valuable for the agent to set expectations, though it does not cover authentication or response format.

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 concise at two sentences, front-loads the core functionality, and includes a meaningful caveat about visibility. No redundant or fluff 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?

For a simple one-parameter tool with readOnly annotations, the description covers the main purpose and key filtering behavior. It lacks an explicit statement about who the athlete id can refer to (self vs others), but given the simplicity, the description is reasonably complete.

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

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

Schema has no description for the 'id' parameter, and schema coverage is 0%. The description contextually implies 'id' refers to an athlete, but it does not explicitly state this or provide any additional semantics like units or expected format.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns activity stats for an athlete, using a specific verb and resource. It distinguishes from siblings like getClubById and getLoggedInAthlete by focusing on stats with a visibility filter.

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 the tool is used for fetching stats for a given athlete, but it does not explicitly mention when to use it over siblings like getLoggedInAthlete or getRoutesByAthleteId. No exclusion criteria or alternative tools are referenced.

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