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

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), and the description adds genuinely non-structured behavior: results are ordered by position on the route with off-road distance, and Balad samples only up to 12 boxes so mid-route places on long trips are missed. That limitation is critical for the agent to know and is available nowhere else.

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 paragraphs: purpose and examples first, then the coverage caveat and the pointer to bl_place. Every sentence carries information an agent would otherwise have to guess.

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 8 parameters, 100% schema coverage and no output schema, the definition covers the essential call semantics plus a return-format hint (km_from_start, off-road distance). It could say slightly more about what each result contains, but 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 coverage is 100% with clear per-parameter descriptions (category slug or free text, limit range, km bounds, open_now, max_off_route_km), so the schema does the heavy lifting. The description adds only the framing that `what` is a single kind of place and that results are measured by km_from_start, which is modest added value over the 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 with scope: 'Find places of one kind ... along the suggested driving route between two points.' The examples ('a gas station on my way to Shiraz') make the along-route concept unmistakable and distinguish it from point-based siblings like bl_nearby and bl_search.

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?

Natural-language example queries tell the agent when this tool fits, and 'Details of a place: bl_place' routes follow-up lookups to the right sibling. It does not explicitly contrast with bl_nearby or bl_nearest_by_drive, so the choice between proximity and route-corridor search is left partly 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds genuine value beyond that: it discloses the return shape (grouped categories with slugs) and that the slugs are the exact vocabulary the sibling tools accept. It omits any note on stability/ordering of the category list, which keeps it from 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?

Two sentences, both load-bearing, with the identification of the tool front-loaded before the when-to-use guidance. The phrase 'with the slug bl_nearby takes' is slightly convoluted but is resolved by the following parenthetical examples, so it costs little.

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 no parameters and no output schema, the description carries the burden of explaining what comes back, and it does so at a useful granularity (grouped categories plus slugs, with example slugs). It is complete enough to call correctly; only sample group names or slug formatting could add more.

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?

Zero parameters, so the baseline is 4; there is nothing for the description to compensate for. It still usefully clarifies that the meaningful output is the slug value rather than the human-readable group label, which is the one semantic ambiguity a parameterless lookup could carry.

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 place categories), and immediately disambiguates the payload as 'the slug bl_nearby takes' plus the grouping structure. This is clearly distinguishable from siblings like bl_search or bl_place, which return places rather than category vocabulary.

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 call it ('when you need the exact slug') and names the three consumer tools — bl_nearby, bl_nearest_by_drive, bl_along_route — with concrete example values (pharmacy, hospital, gas-station, atm, parking). The agent knows both the trigger condition and the downstream purpose without 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?

Annotations already declare this a read-only, idempotent, open-world read, and the description adds non-obvious behavior the schema cannot: results follow Balad's own ordering with site filters applied, each carries a straight-line (not driving) distance, and a free-text category word expands to an entire category with a `category` field disambiguating it. That category-expansion rule is the kind of surprise that would otherwise distort a naive result count.

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 what it returns, then ordering semantics, then sibling routing, then empty-result recovery — no sentence is filler. It is dense and the multi-line layout is longer than strictly needed, but every clause carries information an agent would otherwise have to guess.

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 an 11-parameter, no-output-schema tool it covers returned fields, ordering, distance semantics, category expansion, and empty results. The one omission is what happens past `limit`'s 40 cap (no pagination/offset path is mentioned), which leaves an agent unsure how to retrieve more results.

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 the baseline is 3; the description earns above baseline by explaining that `what` accepts either a slug from bl_categories or free text whose category is then reported back, and by tying `radius_km` to the empty-result remediation. It offers no extra detail on sort, price, min_rating, or limit, relying on the schema for those.

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 and resource ("List places of one kind ... around a point") plus the returned fields, and the category examples (pharmacy, restaurant, gas station) plus the Persian text mapping (پیتزا -> fast-food-restaurant) make the scope unmistakable. An agent can distinguish this from bl_search or bl_place without opening the 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 routes to four siblings with the condition that selects each: bl_nearest_by_drive for driving time, bl_along_route for points on the way, bl_place for hours/photos/reviews, bl_categories for slugs, and bl_search for the origin point. It also prescribes recovery on an empty result (widen radius_km, drop filters, try another word).

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 carry the safety profile (readOnly, idempotent, non-destructive), and the description adds the non-obvious cost model — one route call per candidate — plus the exclusion rule that un-routable places are silently dropped, and the dependency on current traffic. These are behavioral facts an agent cannot infer from annotations or 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 the action and ordering rule, then usage example, then mechanics, then alternatives — a natural decision order for an agent. Every sentence adds information; nothing restates the title or schema.

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 no output schema, the description covers ordering (quickest first) and a key caveat (un-routable places omitted), which is enough to call it correctly. It stops short of saying what each ranked result contains (drive time value, place identifiers), a minor remaining gap for a tool whose response has no 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%, so the baseline is 3; the description goes further by explaining that `candidates` are Balad's top places of that kind in the box as bl_nearby lists them, which links the parameter to a sibling tool's output. It says little extra about open_now or radius_km, but those are already well documented in 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?

States a specific verb and resource: rank places of one kind around a point by driving time, quickest first, under current traffic. The scope (a search box of candidates, not all places) and the distinguishing trait versus bl_nearby (drive-time ranking rather than proximity listing) are both 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?

Gives a concrete trigger question ("which pharmacy / gas station / hospital can I reach fastest from here") and names two alternatives with the condition that selects each: bl_nearby for more places without drive times, bl_place for details of the winner. When-to-use and when-not-to-use are both covered.

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 annotations already declare this as a safe, read-only, idempotent, non-destructive, open-world operation. The description adds useful behavioral context by listing what details are returned and explaining the shape of `hours`, `menu`, and `photos`, though it does not discuss error or freshness behavior.

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 tool's core purpose and remains compact. Each subsequent sentence carries useful scoping, return-field, or sibling-routing 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?

With no output schema, the description adequately enumerates the returned information and clarifies important field semantics like weekday hours formats and photo URLs. It also covers where the required id comes from and when to use sibling tools for related tasks.

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 the parameter definitions themselves are well documented. The description adds meaningful provenance for `id` by naming additional valid sibling sources beyond the schema, though it does not add much about the `photos` and `reviews` count parameters.

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 uses a specific verb and resource: 'Get one place's full details from Balad', then enumerates the exact returned fields. It clearly distinguishes this from siblings such as bl_reviews and bl_route by directing those use cases elsewhere.

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 where the required `id` comes from and explicitly routes the agent to bl_reviews for more reviews and bl_route for directions. It does not spell out a when-not-to-use condition against bl_search or bl_nearby, but the usage context is 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 cover safety (readOnly, idempotent, non-destructive, openWorld), so the description's added value is the geographic boundary and the failure mode ('elsewhere it answers with an error') plus the shape of the returned address. It doesn't discuss partial results, precision, or granularity limits, so not a full 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?

Three short sentences: what it does first, when to use it second, constraint/alternative last. Zero filler and every sentence earns its place.

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 two-parameter read tool with no output schema, the description covers the operation, the returned fields, the geographic scope, the error case, and the sibling alternative. An agent has everything needed to call it correctly and interpret the result.

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 per-parameter examples, so the schema carries the burden. The description's 'covers Iran only' implicitly explains the tight lat/lng bounds but adds no syntax, format, or ordering guidance beyond that; 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 ('turn coordinates into a Persian street address') and enumerates the returned components (city, county, neighbourhood). It also names the sibling it is not (bl_search), so an agent can distinguish it without opening either 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 names the trigger ('user gives a point or a map pin and wants to know where it is'), names the opposite-direction alternative bl_search, and states the exclusion (Iran only). Nothing is left 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?

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the bar is lower; the description still adds genuinely new behavior: 10 per page, newest-first ordering, and a `more` flag driving pagination. It does not cover failure modes (invalid id, empty results, page > 100), which keeps it at 4 rather than 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?

Four short, front-loaded sentences: what it returns, where the id comes from, pagination mechanics, and the sibling alternative. No filler, and the most decision-relevant facts (payload and provenance of `id`) come first.

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 2-parameter read tool with full schema coverage and rich annotations, the description supplies everything still missing: return contents, ordering, page size, and the continuation condition. An output schema would normally cover returns, but here the description names the key fields (stars, rating breakdown, `more`) adequately.

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 the baseline is 3; the description goes slightly beyond by tying `page` to the `more` signal ('call again with page+1'), which is a usage rule the schema cannot express. It otherwise restates the schema's '10 reviews per page, newest first' phrasing.

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 one page of user reviews of a place on Balad') plus the ordering and payload ('newest first, with stars and the rating breakdown'). It also distinguishes itself from sibling bl_place, which 'already includes the first few reviews', so an agent can route 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?

Explicitly says where the required `id` comes from (bl_search or bl_nearby), gives the continuation rule ('when `more` is true, call again with page+1'), and names the alternative (bl_place) that already returns some reviews. That covers when to use, how to continue, and when not to use.

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 readOnly/idempotent/openWorld already declared by annotations, the description still earns credit by disclosing return cardinality (up to 3 routes, suggested first), the meaning of `notes` labels (traffic delay, toll in Toman, fuel use), the conditional `traffic_plan` for restricted zones with hours, and the semantics of the 'no route' error (point outside Iran or off road network). That is behavioral context the annotations cannot carry.

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 core capability, then tiers into return shape, zone behavior, and error cases. Dense but nearly every clause carries information; the parenthetical Persian terms (طرح ترافیک, زوج و فرد) are the one place where length slightly outruns payoff for a non-Persian agent.

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?

There is no output schema, yet the description fully specifies the response shape (routes array, notes labels, traffic_plan, legs) and the main failure mode, so an agent can both call it correctly and interpret what comes back. Nothing material is left to guess.

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, but the description adds real meaning: `stops` produce per-part `legs`, and `traffic_plan` is what surfaces when a stop or endpoint enters a restricted zone. `steps` is not discussed in prose, which keeps it off a 5.

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 driving routes in Iran') plus the payload dimensions (distance, travel time in current traffic, tolls, roads, zone warnings). The Iran scope and driving-only constraint separate it from the coordinate-lookup and proximity siblings without needing their 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 prerequisite chain: 'Get coordinates from bl_search or bl_nearby', which names concrete alternatives an agent needs before calling. It also states when the tool is inappropriate in spirit ('Driving only: Balad's routing answers car routes for every mode'), though it never contrasts with bl_nearest_by_drive or bl_along_route, which is the likeliest sibling confusion.

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 safety (readOnly, idempotent, non-destructive, openWorld), and the description adds real behavioral context beyond them: proximity ranking ('Results near the given point rank first'), the Tehran default when lat/lng are omitted, and recovery guidance for empty result sets. It stops short of stating result ordering guarantees or paging behavior, but the added context is substantive.

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 core action and scope in the first sentence, then organized by concern (geocoding, proximity, types, alternatives, empty-state). Dense but nearly every clause carries information; the run-on sentence listing `type` values and chaining targets is the only place readability suffers.

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 no output schema, the description does explain what results contain (coordinates, address, `id` for bl_place, `category` slug for bl_nearby), which is exactly the missing piece. The `type` parameter that appears only in prose is the notable hole — either the schema or the description is out of sync, leaving the agent unsure how to narrow by result kind.

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 the four real parameters are already documented, but the description describes a `type` parameter ('poi, road, city, region or category') that does not exist anywhere in the input schema. That is actively misleading — an agent may attempt to pass `type` and fail validation. The ranking semantics of lat/lng and the Persian/English query guidance are useful additions, but the phantom parameter drags this down.

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 ('Search Balad ... for places, streets, neighbourhoods and cities by name') plus the return payload (coordinates and address). It also names what it is not — bl_nearby for exhaustive POI sweeps and bl_reverse_geocode for the inverse operation — so an agent can separate it from siblings without opening a 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 two explicit use cases (find a named place; geocode an address/city), an explicit exclusion routed to a named sibling ('For every pharmacy, restaurant, etc. around a point use bl_nearby instead'), a fallback for empty results, and a chaining hint (pass lat/lng from a first bl_search when searching outside Tehran). Nothing is left to inference.

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