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

With no annotations, the description carries the full burden and does well: it discloses sort order (straight-line distance), the conditional default behaviour of radius_m (500m without query, unlimited with query), the limit cap of 50, and that results include serving lines. It stops short of stating read-only/safety semantics or how matching/pagination behaves at scale, but coverage is unusually strong for an unannotated 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?

Front-loaded with the one-line purpose and the routing instruction, followed by a compact per-parameter block where each line adds distinct information. No filler sentences; even the Carris caveat earns its place by preventing wrong-tool use.

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 spelled out, and the description still flags the useful field (serving lines). Combined with full parameter documentation and the coverage caveat, an agent has everything needed to call this 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 0%, so the description must compensate and it does: every one of the five parameters is documented with matching semantics (accent/case-insensitive, all words must match, 6-digit stop id accepted), example queries, coordinate system (WGS84), defaults and max values for radius_m and limit.

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 ('Find Carris Metropolitana bus stops') plus the two lookup modes (name and/or coordinate). It also names the downstream consumer (next_arrivals) and the sibling relationship, so the tool is distinguishable without opening its 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?

Explicitly says 'Use this first whenever the user names a place, street, station or gives a location' and explains why (to get the stop_id needed by next_arrivals). It also adds a when-not caveat: Lisbon city buses are run by Carris, a different company not covered here.

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, the description carries the full burden and does well: it discloses the fuzzy-text fallback behavior for a non-exact line number, the meaning of trips_today=0 (seasonal/weekday-only lines), and the past-midnight time convention like "24:30". It stops short of stating what happens on zero matches or any error condition.

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?

Front-loaded with the resource and return fields, then use cases, then edge-case behavior, then a clean Args block. Every sentence earns its place; the trips_today and midnight-time notes are non-obvious and directly prevent misreading the response.

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 formatting need not be re-explained, and both parameters plus the key behavioral quirks are covered. The remaining gap is failure-mode handling — what an agent should expect when a fuzzy `line` matches nothing at all.

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 entirely, and it does via a dedicated Args block: `line` is either a 4-digit number or free text matched against line names, and `include_stops` triggers an ordered per-direction stop listing. Both parameters gain meaning well beyond their bare string/boolean types.

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 resource (Carris Metropolitana line) and enumerates exactly what is returned: name, route ends, directions, municipalities. The three example questions make it instantly distinguishable from siblings like next_arrivals or find_stops, which cover timing and stop lookup rather than line metadata.

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?

Explicit use cases are given ("where does line 4715 go?", "which bus goes from Cacilhas to Almada?", "check whether a line passes a stop"), and the include_stops flag is tied to the third case. However, it never names an alternative sibling or an exclusion — e.g. it doesn't say to use find_stops when you already have a stop id and want lines serving 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?

With no annotations, the description carries the full burden and does so: it explains the realtime vs scheduled distinction, that minutes_from_now prefers the live estimate, the Europe/Lisbon timezone, and the operational-day limitation. These are non-obvious behavioral traits an agent could not 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?

Front-loaded with purpose and trigger, then behavioral caveats, then per-parameter notes — good ordering with no filler. The args block slightly restates type information that the schema already encodes, but it is earning its place given the 0% schema coverage.

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?

Output schema exists, so return structure need not be explained, yet the description still clarifies how to read each arrival (realtime flag, scheduled caveat, minutes_from_now). For a 3-parameter read tool with no annotations, 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 description coverage is 0%, so the description must compensate and it does: stop_id format (6-digit, example "060361"), line_id (optional 4-digit line, example "2794"), and limit with both default and max (default 10, max 50). That is meaningfully more than the bare schema types.

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+scope: upcoming bus arrivals at a Carris Metropolitana stop, real-time where available. It also names the sibling find_stops as the source of the required stop_id, so the agent can orient without opening schemas.

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 trigger phrase ("when is the next bus at X?") plus the prerequisite step (get stop_id from find_stops first). It also flags a boundary condition — late at night the list may be short or empty — which tells the agent when results should be interpreted cautiously.

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, the description carries the full burden and does well: it warns that an unfiltered call returns ~100 alerts, that alerts are mostly Portuguese-only with a language fallback, and that include_upcoming defaults to True. It omits auth/rate-limit context and does not explicitly state the operation is read-only, which keeps it just short of a 5.

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 summary line is front-loaded, followed by usage and a scannable Args block, so an agent can extract what it needs quickly. There is minor redundancy in restating schema defaults (limit 20, include_upcoming True), but the added format examples justify most of 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?

An output schema exists, so return values need not be described, and the description covers everything else an agent needs: purpose, trigger conditions, all five parameters with examples, the unfiltered-call volume risk, and the Portuguese-only caveat. Nothing material 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 0%, yet the Args block documents all five parameters with formats and defaults: 4-digit line_id with example "4407", 6-digit stop_id with example "160584", include_upcoming default True, language values pt/en with fallback behavior, and limit default 20 / max 100. This fully compensates for the empty 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 first sentence names a specific resource (service alerts) and enumerates its content types (detours, works, strikes, stops not served) for a named operator. That is clearly distinguishable from siblings such as next_arrivals, line_info, and vehicle_positions, which cover schedules, line metadata, and vehicles rather than disruptions.

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 states explicit triggers — "Use before recommending a trip, or when the user asks 'is line X disrupted?'" — and explains the filtering decision (filter by line and/or stop) plus the consequence of not filtering. That covers both when to use it and how to scope the call, leaving little 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?

With no annotations provided, the description carries the full burden and does well: it discloses the returned fields (position, heading, speed, current/next stop) and, importantly, that each fix includes its age in seconds. It does not mention authentication or rate limits, but for a read-only live-data lookup the behavioral disclosure is solid.

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, followed by usage examples and a clean Args section. Every sentence adds information, including the freshness indicator, with 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 one-parameter read tool with an output schema already present, the description is complete: it explains what the tool does, when to use it, the parameter format, and the shape of returned vehicle data. Nothing needed to 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 0%, so the description must compensate. It does: line_id is documented as a 4-digit line number with the concrete example '3508', which is enough to call the single parameter correctly. It could add minor notes about formatting or route variants, but the essential semantics are covered.

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: live GPS positions of buses currently running on a Carris Metropolitana line. It is inherently distinguishable from siblings such as next_arrivals, line_info, and find_stops because it returns vehicle-level positions rather than schedules or stop 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?

It gives clear usage contexts with examples: 'where is the 3508 right now?' or seeing how many buses are out on a line. It does not explicitly name alternatives or when-not-to-use conditions, but the intended scenarios are clear.

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