yerevan-gis-mcp

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

With no annotations, the description carries the full disclosure burden. It adds meaningful traits — server-side execution, grouped output capability, and a performance/precision claim — but leaves key behaviors undisclosed: no explicit statement that it's a read-only operation, no mention of result limits (e.g., max groups returned), and no indication of the return shape despite there being no 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 dense sentences with zero waste: the core function is front-loaded in sentence one, examples follow, and the rationale closes in sentence two. Each clause earns its place, and nothing is repeated from the 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?

For a tool with 8 params, no annotations, and no output schema, the description covers the aggregation semantics well but leaves gaps: how to address the data source (layer_id/layer_key/service_path is undocumented in both schema and description), what the response looks like (single record vs. grouped rows), and the where/order_by behavior. An agent could still invoke it correctly on the required params, but the peripheral params remain a mystery.

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 only 25%, but the description richly illustrates the interaction of the two required params (stat_type, field) plus group_by via examples ('count parcels per district' implies stat_type=count, field=parcels, group_by=district). It does not compensate for the six undocumented params — where, order_by, layer_id, layer_key, service_path — which are essential for actually targeting the data source.

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 (aggregate) on a specific resource (server-side data) with the full operation set enumerated (count/min/max/avg/sum). Concrete examples — 'count parcels per district, average sensor AQI, max reading date' — make the semantics immediately graspable and distinguish it from siblings like query_layer (raw rows) and count_features (count only).

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 for when to use it: 'Cheaper and more precise than pulling rows and summing client-side' implicitly positions it against row-returning alternatives. However, it never names specific sibling tools, doesn't state when NOT to use it (e.g., simple counts could use count_features), and doesn't mention prerequisites like layer identification.

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 behavioral burden. It explicitly says no rows are pulled, that it is cheap, and that it works on any layer. This covers the key behavioral traits for a count operation, though it does not mention error conditions or exact return format.

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, each earning its place: the action, the use case, and the scope. Front-loaded with the core behavior and devoid of fluff.

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 a strong purpose statement, the definition leaves critical calling details unspecified: how to identify a layer among three possible identifiers, whether any are required or prioritized, and what the return value looks like. With no annotations and no output schema, these gaps make the tool incomplete for an agent to reliably call.

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 for the four parameters. It clarifies that 'where' is a filtering clause and that any layer can be used, but it does not explain how to choose among layer_id, layer_key, or service_path, nor does it define the where-clause syntax beyond the default 1=1.

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 ('Count') and resource ('features matching a where clause'), and immediately distinguishes itself from row-returning tools by stating 'without pulling the rows.' This makes it clearly distinguishable from siblings like query_layer.

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 when-to-use guidance: 'Cheap way to answer how many X or to size a query before fetching.' This implies the alternative is fetching rows, but it does not explicitly name a sibling tool or state when not to use 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 behavioral burden. It discloses the operation's nature ('Inspect'), the specific return contents, and a subtle pitfall about layer 0. It does not explicitly state read-only behavior or error handling, but 'Inspect' strongly implies a non-mutating operation and the output list adds meaningful transparency.

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?

Everything is front-loaded: purpose, output detail, input modes, then a crucial caveat. The three sentences are dense but each earns its place, with no filler or repetition of schema 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?

For a tool with 3 optional parameters and no output schema, the description does well: it states what is returned, how to address catalog vs non-catalog layers, and a common domain trap. The main gap is a slight ambiguity about whether layer_id can ever be used alone or must always accompany service_path, and what happens if both layer_key and service_path are supplied.

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 adds value beyond the schema by explaining the relationship between parameters: layer_key is the curated path from search_layers, while service_path + layer_id together reach non-catalog layers. This interaction semantics is not captured in the individual parameter 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 description opens with a specific verb and resource: 'Inspect one layer's schema', then enumerates exact outputs (fields, geometry type, feature count, capabilities). This clearly distinguishes it from siblings like search_layers (catalog search), query_layer (data access), and list_service_layers (layer enumeration).

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 gives concrete input-mode guidance: use a curated layer_key from search_layers, or use service_path + layer_id for layers not in the catalog. It also warns that many Yerevan layers are NOT layer 0, which prevents a common mistake. It does not explicitly state when to prefer describe_layer over query_layer or count_features, but the 'inspect schema' framing makes that mostly implicit.

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 burden of behavioral disclosure. It reveals that results are sorted by distance and that the tool finds the nearest amenity of a chosen kind. It stops short of describing result fields, distance units, or empty-result behavior, but the core behavior is transparent.

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 front-loads the main purpose, then provides the kind list and example queries. Each part earns its place, though the kind list duplicates the schema enum and could be shorter, so it is concise but not maximally tight.

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 five-param geospatial tool with no output schema and no annotations, the description covers the essential intent, sort order, valid kinds, and example tripes. However, it does not state what fields each returned amenity contains, explicitly define the radius and limit semantics beyond schema defaults, or describe fallback behavior when nothing is found.

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 schema covers lat, lon, and the kind enum, but only 40% of parameters have descriptions. The description adds practical value by listing kinds and illustrating radius_m with 'within 1km', but it never explains the limit parameter or explicitly defines radius units. It only partially compensates for the schema coverage gap.

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 ('Find'), a specific resource ('amenities of a given kind'), and explicit behavior ('sorted by distance'). It also enumerates the supported kinds, making the tool's scope clear and distinguishing it from sibling tools like query_near_point or search_street.

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 gives concrete intended-use examples: 'nearest bus stop', 'closest air sensor', 'kindergartens within 1km'. This clearly communicates when to use the tool, though it does not explicitly name alternatives or state when not to use 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses the data source, the conditional behavior based on parameters, the return shape (station reading vs city overview with worst stations), and AQI interpretation bands. It does not discuss rate limits or failure behavior, but for a read-only data lookup the disclosed context is 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?

Three concise, information-dense sentences: scope and metrics, call patterns, AQI thresholds. No fluff, no repetition of schema details, and the most important usage guidance appears early.

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 having no output schema, the description explains what the agent can expect to receive (nearest station reading or average AQI plus worst stations) and how to interpret the AQI values. Parameter semantics, invocation modes, and data scope are all covered sufficiently for correct selection and 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 coverage is 100%, so the schema already documents the parameters. The description adds meaningful semantics beyond the schema by explaining that lat/lon select the nearest station and that omitting them triggers a city-wide overview. This is genuinely useful for choosing whether to pass 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?

States a specific verb and resource: get current air quality in Yerevan from the live sensor network, with named metrics (PM2.5, PM10, NO2, US EPA AQI, temperature, humidity). The 'current' and 'live sensor network' framing distinguishes it from siblings like get_air_quality_forecast and get_station_history.

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 describes two call modes: with lon/lat to get the nearest station, and without location to get a city overview. This gives clear behavioral guidance on how to use the tool, and the 'current' vs forecast/history context implicitly routes the agent away from the relevant siblings.

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?

There are no annotations, so the description carries the full burden. It discloses the model source, the city-wide scope, and the exact output shape (date, predicted AQI, category). It does not mention data freshness or caveats, but for a read-only forecast query it is reasonably transparent.

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. The purpose is front-loaded, and the output/model context fits in the second sentence.

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 one-parameter read-only tool with no output schema, the description covers the geographic scope, forecast nature, model source, and returned fields. A small gap is the lack of date-format or AQI-unit details, but nothing critical 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 single parameter days is fully documented in the schema with default, min, max, and meaning. The description only indirectly references upcoming days and adds little beyond the schema. 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?

The description identifies a specific verb (get), resource (Yerevan city-wide AQ forecast from the Predicted_AQI model), and scope (coming days). It also clearly distinguishes itself from sibling tools like get_air_quality or get_station_history through the forecast and city-wide framing.

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 provides clear context: use when you need predicted city-wide air quality for future days. However, it does not explicitly name sibling alternatives or state when not to use it, so some routing inference is required.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'List' implies a read operation and the free-text/Armenian note is useful, but it does not disclose the output format, ordering, limits, or how layer context is resolved among layer_id, layer_key, and service_path.

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 a single sentence that front-loads the core action and uses an example to clarify. It is reasonably concise, though the parenthetical and example add more length than strictly necessary.

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 five parameters, 20% schema coverage, no annotations, and no output schema, the description leaves important gaps: how the layer is identified, whether 'where' is supported meaningfully, and what the return value looks like. An agent gets enough to know the intent but not enough to invoke it confidently without additional inference.

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 only 20%: the description covers 'field' implicitly but says nothing about 'where', 'layer_id', 'layer_key', or 'service_path'. The description does not compensate for the low schema coverage by explaining how to specify the target layer or apply filtering.

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: 'List the distinct values of one field.' It also gives concrete examples (land-use types, districts) that make the tool's purpose immediately recognizable and distinguish it from sibling tools like count_features or aggregate.

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 clearly identifies when to use this tool: to discover exact Armenian free-text categories before filtering on them. It provides helpful context but does not explicitly name alternatives or state when not to use 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 behavioral disclosure burden. It reveals the output categories and the input format, including the cadastral code prefix range '01-001 … 01-012', but it does not mention error behavior, response structure, or whether active construction projects are returned as a count or a list.

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 two concise sentences with no wasted words. It front-loads the tool's purpose and outputs first, then provides the key input-format detail, making it easy to scan and digest.

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 one-parameter read-only tool, the description is reasonably complete: it names the main return categories and explains the input code convention. Since there is no output schema, a little more detail about the exact shape of the projects field would have been helpful, but the description is still adequate for this low-complexity 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 schema already fully documents the 'district' parameter with examples like 'Erebuni' or '01-005'. The description adds useful meaning by explaining that the tool uses the cadastral code prefix for the district and provides the valid range, which goes beyond 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?

The description clearly states that the tool returns 'a quick statistical profile of one administrative district' and lists specific outputs: parcel count, building count, and active construction projects. It is distinct in content from siblings like list_construction_projects or count_features, though it does not explicitly differentiate itself.

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 intended usage is implied: use it when you need a statistical profile of a single district, using the cadastral code prefix. However, it does not explicitly say when to prefer this over alternatives or when not to use it, so the guidance is present but not fully developed.

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 behavioral disclosure burden. It states that the tool returns yearly totals and specifies the currency (AMD), which clarifies the read-only nature. However, it does not explicitly disclose potential side effects, access constraints, or caveats about data freshness or scope.

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 a single, concise sentence that front-loads the core subject, date range, and output format. There is no redundant or filler wording.

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 parameterless read-only tool, the description fully covers what an agent needs to call and interpret the result: the data domain, the years covered, and the returned fields with units. No output schema exists, but the text explicitly describes the return shape.

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 has zero parameters, so parameter documentation is unnecessary. The description adds contextual meaning by explaining what the returned data contains, which is sufficient given the empty input 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 identifies the tool's purpose: returning municipal kindergarten financing totals per year over 2019-2025, with a specific output format. It is easily distinguishable from sibling tools like list_investment_projects or get_district_profile, none of which cover this exact subject.

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 domain-specific wording implies when the tool should be used: when kindergarten financing totals are needed. However, it does not explicitly mention alternatives, exclusions, or conditions under which another sibling tool might be more appropriate.

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 behavior disclosure burden. It states the output is a PNG image URL, clarifies the required coordinate format, and warns about the MapServer-only constraint. It could say more about errors, auth, or side effects, but 'render and return image URL' is reasonably transparent for a read-oriented mapping operation.

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 four concise sentences with no filler. The main behavior is frontloaded, followed by intended use, required input, and a key compatibility warning. Every sentence contributes.

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 there is no output schema, the description helpfully states the return value is an image URL (href). It also covers required bbox format and service_path constraints. It lacks only minor details such as error behavior for invalid bboxes or missing MapServer services, but the tool is simple enough that the description is sufficiently complete.

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 50%, covering only bbox and service_path. The description reinforces those two parameters and adds the WGS84 bbox format context, but it does not mention width or height. However, width and height are already well constrained by schema defaults and min/max bounds, so the gap is minor.

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 a specific action: render a PNG map image from a MapServer service and return its URL. It also distinguishes itself from sibling query tools by framing it as 'a quick visual of a bounding box' rather than a data query or feature operation.

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 says when to use it: for a quick visual of a bounding box. It also gives a clear when-not: FeatureServers do not expose MapServer endpoints. However, it does not explicitly name an alternative sibling tool to use instead for FeatureServers.

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. It discloses timezone (Yerevan local UTC+4), the measured parameters, and the hourly/recency semantics. It stops short of describing output shape, error conditions, or data availability, but the core behavior is transparent.

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, each purposeful: the first states the core function and output variables, the second supplies the required upstream lookup and timezone. 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?

For a low-complexity read tool with two fully documented parameters and no output schema, the description covers the essential context: what data is returned, the time window, the timezone, and the recommended way to obtain the station code. It could mention response format, but the pollutant list and schema make it 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%, so the parameters are already documented in the schema. The description reinforces station_code and hours by mentioning 'one air-quality station' and 'last N hours,' and adds timezone context, but it does not materially extend the schema's parameter 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 description identifies the specific operation — retrieving historical hourly readings for a single air-quality station over a configurable window — and lists the measured pollutants. This clearly distinguishes it from siblings like get_air_quality (current readings) and get_air_quality_forecast (future predictions).

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 an explicit precondition and routing cue: 'Use get_air_quality first to find a station code.' It does not spell out when not to use the tool versus the forecast sibling, but the context makes the historical-vs-future distinction clear enough.

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 of behavioral disclosure. It conveys that the tool is read-only and that it returns feature-service URLs, which is useful. However, it does not mention authentication expectations, error behavior, whether the item must be public, or the exact response shape, leaving gaps for an agent.

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 two tight sentences with no filler. The core action and scope are front-loaded, and the explanatory clause about revealing feature-service URLs earns its place by clarifying the tool's purpose and 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 one-parameter tool, the description is largely complete: it identifies the input type, where to get the input, and what the output reveals. The lack of an output schema and annotations makes it slightly less complete, but the description covers the essential context an agent needs to use it 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?

The schema already documents item_id as a 32-hex-character string, so baseline is 3. The description adds meaningful context beyond the schema by explaining that item_id comes from search_portal_items or list_public_apps, which helps the agent source valid input values.

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 the specific verb 'Read' and names a precise resource: operational layers of a portal web map or app by item id. It also states the key outcome—revealing the feature-service URLs an app is built on—which clearly differentiates it from related tools like describe_layer or query_layer.

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 gives clear context for when to use the tool by pointing to search_portal_items or list_public_apps as the source for item_id, and frames it as a fast way to discover the data behind a public map. It does not explicitly name alternatives or exclusions, but the source guidance effectively implies the tool is for portal maps/apps rather than raw layers.

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 behavioral burden. It discloses the operation type (point-in-polygon) and the return contents (land category and functional use), which is solid for a simple read-only tool. It does not mention edge cases like points outside the city boundary, but the core behavior is transparent.

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 compact and front-loaded: it states the question, the method, the outputs, and a common use case in two sentences. No words are wasted.

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 two-parameter tool with no output schema, the description adequately covers purpose, method, return values, and a representative use case. It could be more complete by hinting at behavior when the point falls outside the master-plan polygon, but nothing critical is missing for normal calling.

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 input schema already documents lat and lon as WGS84 coordinates with 100% coverage, so the description adds little parameter-specific meaning. It implies they form a location for the point-in-polygon test, but no syntax, units, or range details beyond the schema are provided.

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 identifies the tool's purpose: determining land-use/zoning designation at a location via point-in-polygon against the city master plan. It is specific about the resource and the returned data, but it does not explicitly distinguish this tool from spatial siblings like query_near_point or lookup_parcel.

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 practical guidance with 'Also useful to answer is this area residential / industrial / green / protected,' which helps an agent recognize relevant queries. It does not state when not to use it or name alternatives, but the context is clear enough for common 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?

No annotations are provided, so the description carries the behavioral disclosure burden. It discloses key behavior: optional filtering, the returned fields, and the exact accepted status values with translations. It does not mention potential size/pagination or behavior with invalid values, but the core behavior is clear for a read-only listing 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?

Three concise sentences: purpose, output fields, then status values. Every sentence adds useful information, and the most important filtering details are front-loaded before the output enumeration.

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 optional-parameter list tool with no output schema, the description is nearly complete: it lists the returned fields and filters. Minor gaps are that it does not describe pagination or explicitly state that no filters means a broad default query, but the schema's limit default and maximum mitigate this.

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 67%: status and district are described in the schema, while limit is not but has default/min/max. The description adds value by explaining the exact Armenian status values and their English equivalents, and by emphasizing that filtering by district and status is optional. It does not repeat schema details, and limit needs no additional description beyond schema constraints.

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 the specific verb 'List' with the resource 'construction sites / permits', and states the optional filters and return fields. This makes the tool's purpose immediately clear and distinguishes it from the sibling list_investment_projects by resource type, even without explicitly naming an alternative.

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 clearly indicates when to use the tool: to list construction sites/permit records, optionally by district and status. It provides usage context with valid status values, but does not explicitly say when not to use it or name alternatives like list_investment_projects.

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 transparency burden. It clearly discloses the access limitation: only names and 3D footprints are exposed anonymously, while richer data live in a separate restricted layer. The 'where available' qualifier for Monte subdivision also sets accurate expectations about conditional data.

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?

Both sentences are purposeful: the first states the tool's core action and scope, the second provides an important limitation. The description is compact, front-loaded, and contains no filler or redundant restatement of the tool name.

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 parameterless listing tool, the description adequately covers the return scope: project names, Monte's lot subdivision, and what is intentionally not included. Since no output schema exists, a slightly more explicit statement of the response shape would improve completeness, but the description handles the main use case well.

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 has zero parameters, so the schema already exhaustively defines the input surface. The description correctly avoids inventing parameter details, and the baseline for a parameterless tool is strong. No additional parameter guidance is needed.

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

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

The description opens with a specific verb and resource: 'List the municipality's investment / redevelopment projects by name.' It adds concrete examples and an additional capability (Monte lot subdivision), making the tool's purpose unmistakable and distinguishable from sibling tools such as list_construction_projects.

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 when to use the tool by clarifying it only exposes project names and 3D footprints, and that status, owner, and priority-for-sale data are unavailable. However, it does not explicitly name alternative tools or state when the agent should choose a sibling tool instead, so usage guidance remains partially implicit.

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?

There are no annotations, so the description carries the disclosure burden. It usefully indicates this is a read-only listing and names the returned fields (titles, kinds, viewer URLs). However, it does not disclose whether the list is exhaustive, whether URLs are external, or whether any pagination or staleness behavior applies.

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 front-load the resource and scope, then state the return shape. There is no filler, restatement of the name, or redundant detail.

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 has no parameters, no annotations, and no output schema, the description is complete enough: it defines the resource, gives concrete examples, and explains exactly what will be returned. No critical information is missing for an agent to invoke it 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?

The tool has zero parameters and schema coverage is 100%, so there is nothing for the description to add. Per the baseline for zero-parameter tools, a 4 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 uses a specific verb ('List') and names a concrete resource ('Yerevan municipality's public web apps and dashboards'), with examples that make its scope clear. It is distinguishable from siblings like list_construction_projects or get_air_quality because it targets the app/dashboard directory itself, not underlying project or data records.

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 clearly implies this tool is for discovering public apps and dashboards rather than querying specific datasets, which is enough context for most agent decisions. It does not explicitly name alternatives or state when not to use it, so it stops short of full routing 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?

With no annotations, the description carries the full burden and discloses the return contents ('each layer's id, name and geometry'), the purpose of the output ('pick the right layer_id'), and a real operational quirk ('Yerevan services often skip layer 0'). It does not cover auth requirements or failure modes, but for a read-only listing tool this is meaningful behavioral context.

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, roughly 37 words, with the verb and scope front-loaded. The layer-0 warning earns its place as actionable domain guidance, and there is no filler.

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

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

For a single-parameter tool with a fully documented schema and no output schema, the description covers the essentials: what it operates on, what it returns, and how to use the result. The 'skip layer 0' insight adds real value. It could mention error behavior for invalid paths, but nothing critical 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 100%, with the schema already providing an example path and noting Armenian is allowed and /FeatureServer is optional. The description adds no parameter-level detail beyond what the schema documents, 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?

The description uses a specific verb-resource pair ('List the layers and tables inside a raw ArcGIS service') and immediately scopes the tool to 'services that aren't in the curated catalog', which distinguishes it from siblings like search_layers and describe_layer. An agent can tell exactly what this tool does and why it exists.

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 phrase 'for exploring services that aren't in the curated catalog' gives clear context for when to invoke this tool, implicitly contrasting with catalog-based siblings. However, it does not explicitly name an alternative tool or state when-not-to-use it, so it stops short of the top score.

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?

No annotations are provided, so the description carries the full burden. It discloses the read-style behavior and specifies return fields (code, region/district, subtype, area). However, it does not explain what happens if both code and coordinates are supplied, whether partial matches are truncated by the limit parameter, or how no-result/error cases behave.

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 carry the necessary information with no filler. The lookup modes are front-loaded, and the examples are compact and useful.

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 annotations and no output schema, the description adequately covers purpose, invocation modes, and return fields. The main gap is the limit parameter's effect on prefix-based multi-result lookups, but the schema's default/min/max provide partial context. Overall it is complete enough for an agent to invoke correctly in most cases.

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 75%, with lat, lon, and code already described. The description adds meaningful semantics beyond the schema: it explains full vs partial code formats, that a prefix matches a block/district, and that code and lon/lat are alternative lookup paths. The limit parameter still lacks semantic explanation, but the description compensates well for the main 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 clearly identifies the resource ('cadastral parcel(s)') and the specific action ('Look up'), and it distinguishes two lookup modes: by cadastral code and by lon/lat. It does not explicitly differentiate itself from sibling tools like query_near_point or get_zoning_at_point, but the cadastral scope is specific enough.

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 gives explicit usage guidance: provide a full or partial code for parcel lookup, or provide lon/lat for point lookup, with concrete examples. It does not mention exclusions or alternative sibling tools, but the intended invocation 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?

With no annotations, the description carries the full burden and succeeds. It discloses automatic pagination, geometry being off by default and WGS84 when enabled, free-text Armenian category values, and numeric air-quality metrics stored as strings—none of which are visible 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?

Every sentence earns its place: core purpose, quick-start examples, geometry behavior, vocabulary caveat, and data-type caveat. The phrasing is compact, front-loaded, and free of 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 9-parameter tool with no annotations and no output schema, this description covers the critical operational context: defaults, pagination, geometry, known quirks, and an alternative discovery tool. Nothing essential is missing for an agent to call it 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 coverage is 56%, so several parameters are already documented, but the description adds meaning beyond those field descriptions: the dump-all behavior of where='1=1', automatic pagination, and the data-quality caveats. It doesn't document every parameter, but it enriches the most operationally important ones.

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

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

The description opens with a specific verb and resource ('Run an attribute query against any layer') and a concrete output ('get rows back as JSON'). It calls itself 'the workhorse,' which, among a large sibling list containing describe_layer, count_features, aggregate, and query_near_point, clearly marks this as the generic row-returning query tool.

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 explicit usage patterns: where='1=1' to dump a table, a SQL where clause to filter, and return_geometry=true to get WGS84 coordinates. It also points to get_distinct_values when category spellings are uncertain, which is exactly the when-to-use guidance an agent needs instead of guessing.

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 behavioral burden and does disclose meaningful traits: results are 'sorted by nothing in particular' and distance should be computed client-side if needed. It also explains the radius-0 exact-intersect behavior. It could additionally mention auth requirements, pagination, or output geometry behavior, but the core query behavior is transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with a clear purpose and concrete use cases, and ending with a useful behavioral caveat about ordering. Every sentence adds value and the structure is easy to scan.

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 10 parameters, no annotations, and no output schema, the description is not complete enough. It never explains which parameter identifies the target layer, which is essential since there are three possible layer-identifying parameters. It also omits any clarification of the where clause or geometry return behavior, leaving significant room for incorrect 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 low (30%), and the description does not compensate for the seven undocumented parameters. It fails to explain how to specify the layer (layer_id vs layer_key vs service_path), the meaning of 'where', 'out_fields', 'limit', or 'return_geometry'. The radius-0 explanation is already present 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?

The description states a specific verb ('Find') and resource ('features of a layer within a radius of a lon/lat point'), and makes the tool's purpose immediately understandable with concrete examples. It also clarifies the radius-0 point-in-polygon use case, distinguishing this from generic layer querying.

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 gives clear context for when to use it: nearest bus stops, air sensors, parcel/zoning lookups. However, it does not explicitly mention sibling tools like find_nearby_amenities, lookup_parcel, or get_zoning_at_point, and does not state when NOT to use this tool in favor of an 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?

With no annotations provided, the description carries the behavioral disclosure burden. It does add useful return-field information for plaques versus monuments, but it omits matching behavior, sorting, pagination semantics, and what happens when kind is 'both'. These are meaningful gaps for a tool with no annotation-backed safety or behavior hints.

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 two focused sentences with no wasted words. The search scope is front-loaded, and the second sentence efficiently captures the differing return contents for plaques and monuments. Every sentence contributes essential information.

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 low complexity and the presence of schema defaults for kind and limit, the description covers the essential context: what is searched, in what language, and what each result type returns. Minor omissions like explicit behavior for 'both' and limit application prevent a 5, but the description is largely 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?

Schema description coverage is only 33%, with only 'query' documented. The description clarifies the query text domain (Armenian name/address) and implies the plaque/monument distinction, but it does not explain the 'kind' enum values or the 'limit' parameter at all. This is insufficient compensation for the 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?

The description names a specific verb ('Search') and a distinct resource ('cultural heritage — memorial plaques and monuments'), and specifies the search input (name/address text in Armenian). This clearly differentiates it from sibling tools like search_street or search_layers, which target different data domains.

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 gives clear context for when to use the tool: when searching Armenian cultural heritage records by name or address text. However, it does not explicitly mention when not to use it or name alternative tools for street or layer searches, so it stops short of full exclusion 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?

With no annotations, the description carries the full burden of behavioral disclosure. It does well by revealing what the tool returns, that results are curated, that feature counts are approximate, and that both English and Armenian keywords are accepted. It does not mention pagination, result limits, or error behavior, but for a search/discovery tool this is sufficient.

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 four sentences with no wasted words. It front-loads the core purpose, then gives return characteristics, workflow guidance, and domain/language details in a logical order. Every sentence contributes useful information.

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 discovery tool with no output schema and no annotations, the description is remarkably complete. It explains what is returned, how to use the result, which domains exist, and language support. An agent has enough context to call this tool correctly and know what to do with the output.

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 adds value beyond the schema by enumerating all valid domain values and noting that keywords work in both English and Armenian, which helps the agent construct valid queries. The schema already provides examples for query and domain, so the added value is meaningful but not huge.

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 ('Find datasets'), names the resource ('Yerevan city GIS portal'), and clearly states the output shape (curated layers with layer_key, row semantics, geometry, approximate feature count, domain). It also distinguishes itself from downstream sibling tools by explicitly saying to use search_layers first, then pass layer_key to describe_layer / query_layer / query_near_point.

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 gives an explicit workflow: use this first to discover data, then pass the returned layer_key to the query/describe tools. It also lists supported domains. However, it does not explicitly contrast against sibling search tools like search_street or search_heritage, so an agent might still need to infer when those are more appropriate.

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?

No annotations are provided, so the description carries the burden of describing behavior. It discloses an important exclusion ('Excludes Esri's default basemaps') and the shape of the result ('eturns id, type, title and owner'). It does not mention pagination, ordering, or authentication, but for a read-only search tool these are secondary and the description adds meaningful behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: purpose, exclusion/scope, and use case/return fields. The most decision-relevant information is front-loaded, and there is no fluff or repetition of schema 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?

For a tool with no output schema and no annotations, the description provides suficient context for an agent to invoke it correctly: what it searches, its scope, its exclusions, its use case, and the fields returned. It does not discuss edge cases like empty queries or result truncation, but these are minor given the schema's defaults and the tool's simple search nature.

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 67% with 'type' and 'query' documented. The description adds slight context by naming example item types but does not meaningfully elaborate on the parameters. The 'limit' parameter is self-explanatory from its name, default, and min/max constraints in the schema. Overall the description is not detrimental but provides only marginal added value over 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?

The description clearly states the verb ('Search'), the resource ('the ArcGIS portal's item catalog'), and its scope ('published by the municipality'). It enumerates example item types and explicitly distinguishes itself by noting it 'Excludes Esri's default basemaps' and covers items 'beyond the curated catalog', which sets it apart from sibling tools like list_public_apps.

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 on when to use the tool: 'Use this to discover datasets or apps beyond the curated catalog.' It does not name specific sibling alternatives or provide exclusion criteria, but the phrase 'beyond the curated catalog' strongly implies an alternative curated-list tool and gives an agent enough context to select this over similar 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?

With no annotations, the description carries the behavioral disclosure burden. It explicitly states what is returned (matching street names, toponym id, status), the data source (official register), and a notable behavior (renamed streets found via previous names). It does not cover limit semantics or error cases, but for a read-only search utility this is adequate.

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 three sentences, front-loaded with purpose and context. Each sentence earns its place: one states purpose, one states return values and data source, and one states a constraint plus an additional capability. There is no redundant 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 simple two-parameter search tool with no annotations and no output schema, the description covers the essential aspects: what it does, what it returns, and how queries are constrained. It could explicitly mention limit behavior or result ordering, but nothing critical is missing and the agent can safely invoke the 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 name parameter already has a clear schema description, and the description reinforces the Armenian-fragment requirement but adds little beyond it. The limit parameter has no schema description, and the tool description also does not explain it; however, the schema supplies min/max/default, so the agent can infer its meaning. With 50% schema coverage, the description provides partial but not complete compensation.

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 names a specific operation and resource: 'Search Yerevan streets by (Armenian) name'. It further distinguishes itself from sibling search tools by positioning itself as the portal's stand-in geocoder and specifying that it queries the official street register.

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 clearly says this tool stands in for the real geocoder when a token is unavailable, giving a concrete when-to-use condition. It also notes that names are Armenian only, which implicitly warns against using it for Latin/English lookups, though it does not explicitly enumerate alternative tools.

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