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

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds that the tool returns runtime config values, but does not detail further behavioral traits like auth requirements or data freshness, which is acceptable for a simple read operation with good annotation coverage.

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 well-structured with clear sections for args and returns. Every sentence adds necessary information without 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?

Despite lacking an output schema, the description fully documents the return structure and field semantics. Combined with complete parameter documentation and usage guidance, the description is comprehensive for this simple tool.

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 baseline is 3. The description adds value by providing example values for city_id (e.g., '034' for Shanghai) and explaining the purpose of response_format, exceeding what the schema alone 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?

The name and description clearly state the tool retrieves a city's runtime config (max poll interval and arriving time threshold). The description also distinguishes it from end-user line/stop queries, differentiating it from sibling tools.

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 specifies this tool is relevant for deciding refresh aggressiveness and explicitly says it's not for end-user questions about lines or stops, providing clear usage context. However, it does not name specific alternative tools for those 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?

Annotations already declare readOnlyHint=true, etc. Description adds that subway lines return empty payload with hint field, and explains response structure including 'empty: true' case. No contradiction.

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?

Well-structured with front-loaded purpose and usage, clear parameter list, and organized return value explanation. Every sentence adds value without 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?

No output schema, yet description provides a complete JSON example and explains all keys, special cases (empty response), and relationships with other tools. Comprehensive for a tool with 5 parameters.

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 only 40%, but description adds meaning for all parameters: explains city_id requirement, line_id source, lat/lng usage, response_format options, and maps station fields to other tools. Fully compensates for low schema coverage.

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 clearly states it provides 'Full info for a line: rider-facing fields, full ordered station list, reverse-direction lineId, and every bus currently on the line.' It also differentiates from sibling tool bus_get_timetable with a specific use case.

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 — not bus_get_timetable — to answer "is line X still running" or "first/last bus time" questions.' Also notes subway lines are not supported with clear alternative tools and instruction not to 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?

The description discloses the behavioral trait that only the nearest bus has ETA while others have null, explaining this is not a bug. Annotations already indicate read-only and idempotent, and the description adds extensive detail on output structure and edge cases.

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 well-structured with a clear purpose, important note, argument list, output example, and field notes. Every section adds value, and there is no redundant or wasted text.

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 complexity (7 parameters, realtime data, no output schema), the description is highly complete. It explains parameter construction, output fields, caveats, and references sibling tools for data sources, making it sufficient 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?

The description adds significant meaning beyond the input schema for all parameters, e.g., sourcing guidance for line_id and target_order, fallback instructions for lat/lng, and explanation of response_format. This compensates for the 71% schema coverage.

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 purpose as the canonical 'when will my bus arrive' tool, specifying it returns realtime buses with ETA for the nearest bus. This distinguishes it from siblings like bus_get_timetable (schedule) and bus_list_line_buses.

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 an important caveat about ETA only for the nearest bus and gives fallback guidance for lat/lng parameters. However, it lacks explicit direction on when to use this vs alternatives; the context and sibling names imply the appropriate use case.

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 safe, read-only behavior, but the description adds valuable caveats about terminus omission and point counts, enriching transparency beyond 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?

Well-structured with sections for args, returns, and caveats; every sentence adds value, though slightly lengthy. Could be more concise without losing clarity.

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?

Comprehensively covers parameters, return format, known caveats, and references sibling tools; no gaps given the tool's complexity and lack of output schema.

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 50%; description adds meaningful detail for include_shape and response_format but merely restates city_id and line_id without extra semantics. Adequate but not exceptional.

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 polyline coordinates for drawing a line on a map, and distinguishes itself from sibling tool bus_get_line_detail, which provides authoritative station lists.

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 explicit guidance on when to use include_shape (skip unless needed) and recommends bus_get_line_detail for authoritative stop data, offering clear decision 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 declare readOnlyHint=true, destructiveHint=false. Description adds significant context: precision (city-level ~10 km), data source (ip-api.com), rate limits, no auth, caveats for VPN/cellular IPs, and return structure. 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?

Well-structured with sections: purpose, precision, caveats, args, returns, suggested workflow. Every sentence adds value without redundancy. Front-loaded with the main purpose, followed by important limitations and usage guidance.

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 (2 optional params), the description fully covers inputs, outputs, behavior, limitations, and integration with sibling tools. No gaps remain despite lack of output schema.

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 clear descriptions. The description adds value by explaining the ip parameter's default behavior (omitting uses server's outbound IP) and response_format options. The return example with fields like lat, lng, city, and precision note compensates for missing output 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 the tool resolves approximate location from public IP, specific verb 'Resolve' and resource 'caller's approximate location'. It distinguishes from siblings by stating it's not for precise stop-level queries, and suggests nearby stops tool for that.

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 usage context: 'when user asks what's near me without coordinates'. Provides when-not-to-use: not for stop-level accuracy. Suggests alternative tools and a complete workflow: call this, then use bus_get_nearby_stops or bus_search.

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 idempotentHint=true. The description adds rich behavioral context by detailing the return structure, field notes (e.g., 'buses[].arrivalTime is a ms timestamp', 'capacity: 0=light, 1=moderate, 2=crowded'), and real-time behavior. No contradictions.

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 lengthy but well-structured: purpose first, then usage guidance, then parameter explanation, then full return example with field notes. Every section adds value; no filler. Could be slightly more concise, but overall well-organized.

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 no output schema, the description provides a complete return schema with detailed field notes covering all return fields. It explains how to obtain coordinates, parameter specifics, and response format. For a tool with 5 params and complex output, this is thorough and fully contextual.

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 baseline is 3. The description adds extra semantics beyond the schema, e.g., 'limit: how many of the closest stops to return (max 20)' and response_format explanation. It also clarifies the city_id format. This lifts the score to 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 explicitly states 'List bus stops near a WGS-84 GPS coordinate, each annotated with the lines that pass through and the realtime buses approaching.' This clearly defines the verb (list), resource (bus stops), and scope (near coordinates with lines/realtime), distinguishing it from siblings like bus_get_stop_detail (specific stop) and bus_search (by name).

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 explicit guidance: 'If you don't have coordinates: call bus_get_my_location first... or ask the user for a landmark and resolve it via bus_search.pois.' This tells the agent when to use alternatives, clearly separating this tool from coordinate-requiring tools.

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 description provides detailed behavioral context beyond annotations: it explains the meaning of the 'distance' field (populated by lat/lng) and that multiple stations in the output correspond to multiple physical platforms. Annotations already indicate read-only/idempotent, so the description adds useful nuance.

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 well-structured with a summary line followed by an Args list and a Returns example. It is slightly long but every sentence adds value; the structure aids readability.

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 7 parameters and a rich output, the description covers all parameters with explanations, provides a concrete output example, and explains edge cases (multiple platforms). No output schema exists, but the example fully compensates.

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 description adds meaning to parameters beyond the schema by explaining sources (e.g., physical_st_id from bus_get_nearby_stops) and usage tips (e.g., namesake_st_id recommended). Since schema coverage is 86%, the description compensates well for the remaining 14%.

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 starts with "Full detail for a stop" and lists what is included (coordinates, lines, realtime buses, metro lines), clearly distinguishing it from sibling tools like bus_get_nearby_stops (which lists stops) and bus_get_line_detail (focuses on a line).

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 explains where the input parameters come from (e.g., bus_get_nearby_stops / bus_search) and marks namesake_st_id as recommended, giving usage hints. However, it does not explicitly compare to sibling tools or state when not to use this tool.

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 and idempotent. Description adds three behavioral modes (scheduled, interval, special) and sample output, providing good context beyond annotations. Could mention rate limits or error responses, 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?

Description is concise, well-structured with clear sections, and uses formatting (bold, code) to highlight key points. No unnecessary 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?

For a simple read-only tool with good annotations, the description provides complete context: purpose, behavior modes, parameter guidance, and a sample return. Missing output schema is compensated by inline description of return fields.

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 covers 40% of parameters with descriptions (line_no and response_format). Tool description reinforces those and adds critical warning about line_no (not internal line). For other params (city_id, line_id, direction), no extra detail, but the warning for line_no is valuable.

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?

Title and description clearly state this tool returns per-trip schedule, and explicitly warn that most lines in Shanghai operate on fixed intervals, making this tool rarely useful. It distinguishes itself from siblings like bus_get_line_detail.

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?

Description explicitly tells when not to use it (most lines are 'interval') and directs users to bus_get_line_detail for common queries like first/last bus times. This is excellent 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 show readOnly/destructive/idempotent hints. Description adds full return JSON structure and explains behavior of hot_only parameter. No contradictions.

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?

Concise yet complete: purpose, args, returns, usage guidance all in few sentences. Each 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?

Given no output schema, description provides sample JSON structure. Covers all relevant behavioral aspects for a simple list tool.

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 covers both parameters well (100% coverage). Description adds value by warning about token-heavy full list and alternative usage. Would be 5 if it added more details on response_format behavior.

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?

Explicitly states 'List cities supported by the realtime bus data service.' Verb is 'list', resource is 'cities'. Clearly distinguishable from sibling tools which deal with lines/stops/etc.

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 explicit usage guidance: 'Use when: the user mentions a city name and you don't have its ID.' Also warns about token cost when using full list.

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?

Adds significant context beyond annotations: discloses that despite the name 'busList', it returns at most 1-2 buses (imminent ones), and explains the narrow scope. No contradictions with annotations (readOnlyHint, destructiveHint, etc.).

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?

Well-structured: summary, caveat, usage guidance, parameter list, return example. Every sentence adds value, no unnecessary words. Front-loaded with key info.

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?

Includes sample return JSON and usage guidance, but lacks handling of edge cases (e.g., no bus found) or error info. Still sufficiently complete for correct invocation given the sample and sibling contrast.

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 40% (low). Description adds meaning for target_order ('the waiting stop's order') and clarifies station_name, but city_id and line_id are not explained beyond schema. Acceptable compensation for low coverage, not outstanding.

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 clearly states it returns the nearest approaching bus with ETA, contrasting with bus_get_line_detail which returns full roster. The verb 'returns' and resource 'nearest bus' are specific, and the sibling differentiation is explicit.

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 tool when you want a quick "what's about to arrive" answer' and directs to bus_get_line_detail for full bus list, providing both context and alternative.

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 show readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds crucial behavioral context: coordinate system GCJ-02, return format, line types (0=bus,1=metro), duration/distance units, and a note field for suspicious responses. No contradictions.

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?

Well-structured with sections: purpose, coordinate note, args, return example. Front-loaded with core purpose. Every sentence adds value, though length could be slightly reduced.

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 9 parameters and no output schema, the description is thorough: covers all params, return shape, edge cases (strategy 3, coordinate conversion). Lacks error handling details, but acceptable.

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 high (89%). The description adds meaningful context beyond schema: explains coordinate system origin, strategy nuances (3=bus-only), and default behavior. Includes a return example that clarifies parameter usage.

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 plans a public-transit route between two points and returns alternative plans. It distinguishes itself from sibling tools like bus_search (which searches stations/POIs) and bus_get_line_* (line details) by focusing on route planning with segments.

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 clear context on when to use: for planning transit routes. Advises on coordinate conversion and strategy selection (recommending 0 for most cases). Does not explicitly list when not to use, but sibling list and purpose make it clear.

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, idempotent, etc. The description adds the important soft cap of 10 quadruples per call and provides an example of the return structure, going beyond annotation details. No contradictions.

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 well-structured: one-sentence summary, bulleted parameter details, a concrete example, and a note on the soft cap. Every sentence adds value without 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 complexity (batch operation, three parameters), the description covers all essential aspects: purpose, parameter semantics, usage scenario, output format (via example), and a usage limit. Sibling tools are numerous but the description clearly distinguishes this batch tool.

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 description provides a detailed format for the complex 'line_stn' parameter with precise quadruple syntax and an example, significantly augmenting the schema's minimal description. The 'response_format' parameter is also clarified.

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 title and description clearly state that this tool batch-refreshes realtime info for multiple (line, stop) pairs, specifically targeting a 'favourites' dashboard. It is distinct from siblings like bus_get_line_realtime which handles a single line.

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 mentions the use case ('favourites dashboard') and implies it is for batch operations in one round-trip, but does not explicitly contrast with single-pair alternatives such as bus_get_line_realtime.

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 idempotent. The description adds a specific edge case: for municipalities, the upstream emits empty 'city' but the tool back-fills with 'province'. This is valuable beyond 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?

Description is well-structured: main sentence, usage guide, args list, return structure, special note. No redundant content, front-loaded with key info.

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 (3 params, flat structure), the description fully covers purpose, parameters, return format, and edge cases. No output schema needed due to detailed return description.

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%, but description adds examples, explains coordinate system (WGS-84), and details the response format including the back-fill behavior for city. This greatly enhances parameter understanding.

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: 'Convert WGS-84 lat/lng to a Chinese postal address'. The verb 'convert' and resource 'lat/lng to address' are explicit, and the tool is distinct from bus-route siblings.

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 'Useful when you have raw GPS coordinates and need a human-readable place name, or the citycode/adcode to pass to other tools.' Provides clear context, though no exclusion or alternative is needed.

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, destructiveHint, idempotentHint, openWorldHint. The description adds critical details: coordinate systems (GCJ-02 for pois, WGS-84 for stations), line folding, subway handling (bus_get_line_detail empty for subways), and special cases for missing station IDs. No contradictions found.

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?

Well-structured with clear sections (main usage, keyword tips, coordinate systems, return example, line folding, subway hint, follow-ups). Front-loaded with essential info. Slightly long but every part adds value; minor redundancy in repeating schema's args briefly.

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 complexity (three entity types, coordinate differences, line directions, subway exceptions), the description is extremely thorough. It covers empty results, coordinate usage, line ID selection, subway handling, and follow-up tool usage. No output schema, so the detailed return example compensates perfectly.

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%, but the description significantly enriches parameter meaning: keyword tip (plain numbers, suffixes), city_id example, response_format effect. Also explains return structure in depth, which aids understanding of how parameters affect results.

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 searches by keyword and returns lines, stations, and POIs in one call. It distinguishes itself as the primary entry point for user queries without IDs, setting it apart from siblings like bus_search_more.

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 advises using this as the primary entry point for line numbers, station names, or destinations without IDs. Provides tips for handling empty results (appending '路') and includes a follow-ups section directing to specific tools for each part of the return 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 declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, establishing safety. The description adds the behavioral detail that the return shape matches bus_search but only the requested category is populated. This goes beyond annotations by clarifying the output structure and relationship to bus_search.

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: one sentence for purpose, then a bulleted list of Args. Every sentence provides essential information. No fluff or redundancy. Front-loaded with the main intent.

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 4 params, no output schema, and annotations covering safety, the description provides sufficient context: purpose, relationship to bus_search, parameter explanations, and return shape. It lacks explicit pagination mechanism details (e.g., offset/limit) but the 'see more' concept is clear. Overall adequate for the tool's 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% (all parameters described). The description adds context: keyword must be 'same keyword used in bus_search', and explains the type parameter values as 'more lines', 'more stations', 'more POIs'. This adds meaning beyond the schema's examples and enum labels.

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 is for paginated 'see more' for one category from bus_search. It identifies the specific verb 'search more' and resource 'results of one category', and distinguishes itself from the main bus_search tool. The sibling tools include bus_search, so the differentiation is clear.

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 after bus_search to paginate results for a specific category. It says 'Paginated "see more" for one category from bus_search.' which indicates context of use. However, it does not explicitly state when not to use it or provide alternatives, but the linkage to bus_search is clear enough.

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