Shreddy

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the description is not needed to establish safety. It earns credit for disclosing the non-obvious failure mode (private/removed/missing all collapse into not found) and the untagged-rider case where crossings have no lap — behaviors an agent cannot infer from 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?

The core action and the payload summary are front-loaded, and no sentence is filler. However, the long middle sentence dissecting `timing` fields is dense and overlaps heavily with what the output schema already declares, making it the least earned portion.

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?

An output schema exists, so the description need not enumerate return fields, yet it covers the one thing the schema likely cannot: the semantic of an absence (not-found collapsing) and untagged-rider timing. Nothing critical for correct invocation appears 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 id parameter already documents both the integer/string union and the URL form (the number in /clips/<id>). The description adds nothing about the id format beyond what the schema provides, so the 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?

"One public clip by id" states the specific resource and cardinality, making it distinguishable from search_clips and list_venues. The follow-on enumeration of what is returned (measurements, calibration, rider breakdown) reinforces scope, though siblings are not named explicitly.

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: this is the single-item fetch keyed by id, versus the search/listing siblings. There is no explicit when-to-use-this-instead-of-search_clips guidance, but the 'private, removed or does not exist all read as not found' sentence usefully tells the agent how to interpret an empty result and that it need not retry.

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 (readOnly, idempotent, non-destructive, closed-world), so the description is free to add output semantics, which it does: top-3 limits, "biggest first" ordering, newest-clip inclusion with links and optional lap times, and the limitation "no lap record yet." That disclosed gap in record coverage is genuinely useful context an agent cannot get from 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?

One dense sentence, front-loaded with the core promise, and nearly every clause carries distinct information rather than filler. It is a bit over-packed for a single sentence (nested parentheticals make it less scannable), but nothing is redundant with the annotations.

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?

An output schema exists, so return-shape explanation is not strictly required, yet the description still covers record ordering, truncation at top 3, and a known missing field — enough for an agent to call it and interpret results confidently. Only the not-found/ambiguous-name case is left unaddressed.

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 `venue` property already documents 'name or id' with the same examples, so the description's final sentence largely restates the schema. Baseline 3 applies; it adds no resolution rules for ambiguous names or case sensitivity beyond the schema itself.

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+resource framing ("Everything about one bike park in one call") and then enumerates exactly what is returned: runs with clip counts, clip/ride totals, records, and newest clips. That scope implicitly separates it from get_clip (single clip) and list_venues (many parks), though no sibling is named explicitly.

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 only implied by the content list — an agent can infer you call this to get the full profile of one park. There is no explicit statement of when to prefer it over search_clips or get_clip, and no mention of behavior when the venue is unknown or ambiguous.

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, non-destructive, and closed-world, so the safety profile is covered. The description adds non-obvious behavior beyond that: only venues with public clips appear, distances are returned in both km and miles, and `near` requires numeric coordinates even for place names.

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 resource and scope, then filtering behavior, then the usage cue. The enumeration of return fields is dense but every clause carries information an agent needs 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?

An output schema exists, so return values need not be explained; annotations cover safety. The description still supplies the scoping constraint, filter semantics, and unit behavior, leaving nothing an agent needs to call this three-optional-parameter 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?

With 100% schema description coverage the baseline is 3, and the description largely restates the schema: query matches name/city/state and near takes coordinates. The only added nuance is that place names must be geocoded to lat/long, which the schema also hints at, so it adds little beyond structured data.

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

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

States a specific verb and resource ("List the bike parks (venues)") and narrows scope to those with public Shreddy clips. It also names the returned fields and a distance-sorting behavior, which lets an agent distinguish it from get_venue (one venue) and search_clips without opening any schema.

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?

Gives an explicit use case ("what parks do you have") and a secondary purpose ("learn valid venue names"), which is valuable guidance for a discovery tool. It does not name when to prefer a sibling such as search_clips instead, so it stops short of full alternative routing.

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 (readOnly, idempotent, non-destructive), and the description layers on non-obvious behavior: ranked results fan out group clips per rider and exclude rides with no metric value, newest results include uncalibrated clips, and each clip carries a viewer link plus `lap_time_s` when available. It also spells out the cursor round-trip, which is exactly the kind of operational detail annotations cannot convey.

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?

Purpose is front-loaded and every sentence carries information, including the pagination instructions at the end. It is dense — the parenthetical about group clips is a long clause — but nothing is redundant enough to cut without losing meaning.

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

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

Despite 10 optional parameters, an output schema, and three sort modes, the description covers filtering, ranking semantics, result composition, and pagination. The output schema handles return shape, so the remaining narrative is exactly the right scope.

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 already 100%, yet the description adds cross-parameter semantics the schema can't express: metric-without-sort defaults to biggest, since/until outrank `when`, `feature` works without a venue and accepts names like 'double black', and lap times are returned but cannot be ranked. That is genuine value beyond the structured fields.

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

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

Opens with a specific verb+resource pair, 'Search public clips', that immediately separates it from get_clip and the venue tools. The rest of the description elaborates scope (public, newest-first) rather than restating the name, though it never explicitly contrasts itself with a sibling.

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?

Gives concrete conditional guidance: default is newest, a bare `metric` implies 'biggest', `since`/`until` override `when`, and a newest search includes unmeasured clips while ranked searches drop them. It stops short of stating when to prefer this over get_clip, but the resource split makes that largely self-evident.

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