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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds genuinely useful non-obvious context: that active-period evaluation happens in Europe/Bucharest and that both current and historical alerts are returned. It stops short of noting data freshness or rate limits.

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 tight sentences, front-loaded with the core action, and the timezone note earns its place as non-obvious behavior. 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?

With an output schema, full schema coverage, and rich annotations, the description covers what the agent needs to call it correctly. Only the sibling relationship to get_service_status is unaddressed, which is a minor gap.

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

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

Schema description coverage is 100%, so all four parameters are already documented. The description reinforces that line and stop_id are optional filters ('when supplied') and adds timezone context for active_only, but supplies no format or semantics the schema lacks. 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?

States a specific verb and resource ('Get ... STPT service alerts') and clarifies the current-vs-historical scope. It is distinguishable from most siblings like get_arrivals or get_vehicles, though it never explicitly contrasts with get_service_status, which is the nearest sibling and could be confused with it.

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?

'Filters by stop ID and/or line when supplied' implies how to narrow results but gives no explicit when-to-use guidance or exclusions relative to get_service_status or get_arrivals. The agent must infer that this is the tool for alert text as opposed to arrival/status data.

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

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

Annotations already cover read-only/idempotent safety, and the description adds genuinely new behavior: live data only when freshness is verified, GTFS fallback otherwise, and which fields reveal provenance. That is meaningful context beyond the structured hints, though it doesn't mention rate limits or ordering guarantees.

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 tight sentences, front-loaded with the purpose, then the data-source caveat, then the fields to check. No sentence is redundant.

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, yet the description helpfully points at the exact provenance fields an agent should inspect. Nothing necessary for correct invocation 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 stop_id, line, and limit are fully documented in the schema. The description adds no syntax, format, or defaulting detail beyond that, 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?

States a specific verb and resource ('Get upcoming arrivals at an STPT stop'), which clearly separates it from get_stop, get_vehicles, and the other siblings. It doesn't explicitly name an alternative tool to route away to, but the resource is 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 implies the use case (fetching arrivals for a stop) but gives no explicit when-to-use vs when-not guidance and never references sibling tools like get_stop or get_vehicles. The fallback explanation is behavioral rather than selection 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 readOnly, idempotent, non-destructive, and openWorld, so the safety profile is covered. The description adds genuine context beyond them: that the response includes bundled feed metadata and 'bounded' cache statistics, plus the assurance 'Contains no secrets,' which matters for an externally exposed status endpoint.

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 short sentences with no filler, and the primary payload (what is reported) is front-loaded before the safety 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?

An output schema exists, so return-value details need not be in the description, and the annotations cover the safety contract. For a zero-parameter read-only status tool, nothing an agent needs in order to call it 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. It correctly avoids inventing parameter semantics that do not exist.

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?

Uses a specific verb ('Report') with a concrete list of resources: readiness, version, bundled network feed metadata, and bounded cache statistics. This is unmistakably a service-health tool and cannot be confused with any of the transit-data siblings such as get_vehicles or get_alerts.

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 stated contents imply a health/diagnostics use case, but the description never says when to call it, whether it should be polled, or how it relates to the sibling tools. Since no sibling covers the same ground, the missing guidance is less costly, leaving it at implied-only 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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description adds useful scope information by naming the returned facets (including neighboring stops, a non-obvious extra), but says nothing about behavior on invalid IDs or how fresh/complete the data is.

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 tightly packed sentence: the action leads, the returned fields are enumerated, and the input constraint trails. Zero 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?

With an output schema covering return shape and annotations covering safety, the description is nearly complete. The only residual gap is how an agent should obtain a valid stop ID (e.g., via search_stops), which would round it out.

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 is documented as 'Numeric STPT stop ID.' The description restates the same constraint without adding format, range, or sourcing guidance, 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?

States a specific verb+resource ('Get ... stop details') and enumerates exactly what is returned: coordinates, serving lines, directions, terminals, and neighboring stops, keyed by a numeric STPT stop ID. This distinguishes it well from siblings like get_arrivals, though it does not explicitly contrast it with search_stops.

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 'numeric STPT stop ID' phrasing — an agent can infer it is the lookup-by-ID tool versus search_stops' query-based discovery, but no when/when-not or alternative is named. No prerequisites or failure conditions for an unknown ID are mentioned.

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 establish this as a safe, read-only, idempotent operation, so the description doesn't need to cover safety. It adds useful behavioral context by disclosing that each vehicle carries an upstream observation timestamp and staleness flag, which tells the agent how to interpret data freshness. It does not mention pagination or limit behavior, but that is a minor gap given the annotations and output 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?

Two concise sentences, front-loaded with the purpose and followed by the optional filter and data-quality note. No 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?

The tool is simple: two optional parameters, full schema coverage, annotations covering safety and openness, and an output schema that documents return values. The description is complete enough for correct invocation. It could be improved by noting when to prefer this over get_arrivals or other siblings, but that is outside the core completeness of this definition.

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 the 'line' filter and 'limit' cap are already documented in the schema. The description only restates the optional line filter and adds no syntax, format, or default details beyond the 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?

The description states a specific verb ('Get') and resource ('current STPT vehicle positions'), making it immediately distinguishable from siblings like search_stops, list_routes, and get_arrivals. No tautology or 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?

It implies usage through 'current' positions and an optional line filter, but gives no explicit when-to-use/when-not guidance, no alternatives among the sibling tools, and no prerequisites. The reader must infer the role of this tool from the resource 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 read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds one genuinely useful fact beyond that: results come from a static bundled GTFS-derived snapshot rather than live data. It says nothing about result size, ordering, or pagination.

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?

A single front-loaded sentence with the resource and data source in the opening clause. It is terse and free of filler, though the mode list it adds is both redundant with the schema and inaccurate.

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-value explanation is not required, and there are no required parameters. What is missing is any guidance on filtering semantics or on the static-vs-live distinction's implications, plus the inaccurate mode list, leaving the definition only minimally sufficient.

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

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

Schema coverage is 100% for the single optional `mode` parameter, which sets a baseline of 3, but the description names modes ("metropolitan, express") that are not valid values in the VehicleMode enum (tram, trolleybus, bus, vaporetto, unknown). This misleads the agent rather than adding meaning, so it scores below baseline.

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 STPT ... routes") and scopes it to the bundled GTFS-derived snapshot, which clearly separates it from siblings like search_stops or get_vehicles. It does not explicitly name an alternative, so it stops short of full sibling differentiation.

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 statement of when to call this versus search_stops, get_stop, or get_service_status, and no guidance on when the mode filter should be applied. The agent must infer usage entirely from the name and the mode enumeration.

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, non-destructive and open-world. The description adds genuine behavioral detail beyond them: diacritic-insensitive matching and a hard result cap of 50, both of which affect how an agent should query and interpret results.

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 with no filler, and the core action and scope are front-loaded before the matching and result-count 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 an output schema present and full parameter documentation, the description covers what is needed to call the tool correctly. The only omission is how the tool relates to the sibling get_stop for exact-ID lookups.

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 query and limit are already documented with examples and bounds. The description's mention of 'up to 50 stops' and the match types only restates schema-level facts, 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?

Specific verb (Search) plus resource (STPT stops) and explicit scope ('bundled STPT network'). It also names the three match keys, so an agent can immediately tell this apart from get_stop (single-stop lookup) and list_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 implies usage through the set of searchable keys (stop ID, name, line), which lets an agent infer when to reach for it. However, it never explicitly says when to prefer it over the sibling get_stop, nor any exclusions or prerequisites.

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