heart-routes

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

No annotations provided, so description carries full burden. It discloses that donation goes to external sites and that the link is embedded in GPX metadata. However, it does not mention potential side effects, idempotency, or permissions needed. Basic behavioral info but lacks depth.

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

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

Two sentences, no fluff. First sentence states purpose, second adds critical clarification about donation flow. Front-loaded and efficient.

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

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

Given simple tool with 2 params, no annotations, no output schema, the description covers main purpose and clarifies external payment. However, it does not explicitly state what the tool returns (likely the builder URL). Slightly incomplete but adequate for simple case.

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

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

Schema coverage is 100% with descriptions. The description adds example domains for fundraising_url and clarifies city as optional. This is a minor addition beyond schema, so baseline 3 applies.

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

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

Clearly states 'Compose a builder URL with a fundraising link pre-filled' and explains embedding in GPX metadata. Distinguishes from siblings by specifying fundraising purpose, unlike add_dedication which probably adds a different type of content.

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

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

Provides context: URL surfaces in Strava after sync, CityHeart does not handle payments. Implicitly tells when to use (to attach a fundraising link), but does not explicitly say when not to use or compare to alternatives like add_dedication.

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

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

No annotations, so description carries burden. States 'Pure URL builder, no server-side state' which is key. But does not mention error conditions, validation, or what happens if name is invalid. Adequate but could be more detailed.

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

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

Three sentences, front-loaded with action and effect. No wasted words. Every sentence adds value: purpose, usage context, and behavioral note.

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 URL builder with 3 params and no output schema, the description covers purpose, usage, and behavior. Missing return value description (the composed URL) which is a gap, but otherwise adequate for the 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 coverage is 100% and each parameter has a description. The description adds context that parameters pre-fill the builder URL, but does not add meaning beyond schema. 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?

Clearly states it composes a builder URL with a dedication pre-filled, specifying the effect on GPS watch and Strava title. Distinguished from sibling route-finding tools by saying 'Use after the user picks a route'.

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

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

Explicitly says when to use: after picking a route and deciding who the heart is for. Also clarifies no server-side state. Does not mention when not to use or alternatives like add_cause.

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

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

No annotations provided, so description carries full burden. It discloses that the tool returns a URL (not the file), involves a one-time €4.99 payment through Stripe, and that CityHeart never charges through chat. This gives important behavioral context about the checkout process. Could mention what happens if route is not public or if payment fails, but overall strong.

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

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

Two sentences: first states purpose, second gives usage order and payment note. Every sentence is necessary and efficient. No 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?

Given one parameter with full schema coverage and no output schema, the description is complete. It explains the tool's role in the workflow (post-confirmation), the payment handling, and the external site. Siblings cover other aspects, so this is 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?

Only one parameter 'slug' with 100% schema coverage. The description adds that the route must be public and final, but does not provide new syntactic details beyond the schema's example. 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 it returns a GPX download/checkout URL for a specific public route. It distinguishes from sibling tools like find_heart_route_in_city or get_route_details, which are about route discovery rather than export.

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

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

Explicitly states to use 'after the user has picked a final route (find / get_details) and confirms they want it.' This gives clear when-to-use context and implies not to use before confirmation.

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

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

With no annotations provided, the description must cover behavioral traits. It states it returns up to 5 AI-validated routes and mentions optional distance filtering. However, it does not disclose what happens if no routes are found, authentication needs, or rate limits. The description is adequate but has gaps.

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

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

The description is two sentences, front-loaded with the core action, and includes illustrative examples. No redundant or wasted words. Every sentence adds value.

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

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

The tool has 3 parameters, no output schema, and no annotations. The description explains the main functionality and gives usage context, but does not describe return format, error handling, or behavior when no routes match. Given the lack of output schema, some return 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?

Schema description coverage is 100%, so baseline is 3. The description adds minimal additional meaning beyond the schema, mainly paraphrasing 'optionally a target distance'. It does not enrich understanding of 'prefer_gold' or 'max_distance_km' beyond existing schema 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 explicitly states the verb 'Find', the resource 'existing heart-shaped running route', and the scope 'in a given city'. It distinguishes from siblings like 'generate_heart_route' by focusing on existing routes, and provides concrete example user queries.

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 clearly indicates when to use this tool: 'when a user mentions a city and wants a heart route'. It gives example triggers and implicitly distinguishes from generating a new route. However, it lacks explicit when-not-to-use scenarios or alternative sibling mentions.

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

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

With no annotations provided, the description carries full burden. It discloses the dual return type (existing matches + deep-link), explains the builder pre-fill, and mentions CityHeart never touches money. However, it lacks details on failure modes, rate limits, or side effects of generation.

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

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

Three sentences front-loaded with the action and key outcomes. No wasted words. Every sentence adds necessary context.

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 5 parameters, no output schema, and multiple siblings, the description adequately covers purpose and usage. It mentions return type (existing matches + deep-link) but lacks detail on response format or what happens on error, which would improve 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?

All 5 parameters are fully described in the schema (100% coverage). The description adds extra value by explaining how 'dedication' and 'cause_url' pre-fill the builder fields, which is not in the schema. This goes beyond the baseline of 3.

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

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

The description clearly states the tool action: 'Start a new heart-shaped route for a given city.' It differentiates from siblings like 'find_heart_route_in_city' by explaining it returns both existing matches and a deep-link for fresh generation, showing specific verb+resource+scope.

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: 'when the user explicitly wants a NEW heart, or when an existing match is close enough but not personal yet.' It provides clear context for selection, though it does not include exclusions or alternatives explicitly beyond the sibling distinction.

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

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

No annotations provided, so the description carries full burden for behavioral traits. It does not disclose that the tool is read-only, idempotent, or any authentication or rate limit requirements. Only return fields are listed.

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 concise sentences, no redundant information, front-loaded with purpose and output summary.

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 no output schema, the description covers purpose, usage context, and return fields. It lacks error handling or edge case info, but is adequate for the 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 coverage is 100% with a clear description and example. The description adds only contextual usage (comes after find_heart_route_in_city), but does not significantly expand on the parameter's meaning beyond the schema.

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

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

The description clearly states it gets full details for a specific heart route by slug, lists returned fields, and distinguishes from sibling tool find_heart_route_in_city by specifying its place in the workflow.

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

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

Explicitly guides when to use: 'Use after find_heart_route_in_city when the user picks one.' This provides clear context, though it doesn't explicitly exclude other use cases.

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

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

With no annotations, description carries full burden. Discloses return format (city names + route counts, sorted by inventory size) but does not specify sort order (ascending/descending) or other behaviors like pagination, auth requirements, or side effects.

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 action and usage guidance. Every sentence adds value with no 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?

Given the simplicity (1 optional param, no output schema), description covers purpose, usage context, and basic output. Lacks mention of the 'limit' parameter and exact sort direction, but overall adequate.

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% (one parameter documented), so baseline 3. Description adds no additional meaning about the 'limit' parameter beyond what schema provides.

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

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

Description uses specific verb 'list' and resource 'cities with at least one heart route available', clearly distinguishing it from siblings like 'find_heart_route_in_city' which operates on a selected city.

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

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

Explicitly states when to use the tool: 'when the user asks where can I run a heart? or hasn't picked a city yet'. Does not mention when not to use or name alternatives explicitly, but context implies alternatives.

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