Istanbul MCP

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

Annotations already establish that this is a safe, read-only, idempotent operation. The description adds useful behavioral context beyond them: district-only queries may return address lists without WiFi or invented distances, and geocoding is not full address geocoding.

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 purpose is front-loaded, and the remaining sentences each add a concrete constraint or disambiguation rule. The examples and exclusions earn their place, and the description is appropriately sized for a six-parameter tool.

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

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

The description covers usage constraints and some return behavior, but with no output schema it does not describe what the summarized WiFi/library results look like. It also leaves limit semantics undocumented, so an agent has gaps for correct invocation and result interpretation.

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?

With 0% schema description coverage, the description carries the burden and explains the main ambiguous inputs: district/place/coordinates exclusivity, radius applicability, and the Acıbadem disambiguation. It does not explain the limit parameter, but most semantically important parameters are covered.

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

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

The description states a specific verb (summarize) and resources (WiFi and district-level libraries/culture), with scope near a reference point or district. It is clear enough to distinguish this from generic nearby tools, but it does not explicitly name alternatives such as istanbul_nearby or istanbul_mobility_nearby.

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 constraints: district is exclusive with place/coordinates, district-only place names return address lists, radius only applies to WiFi with a point, and ambiguous names like Acıbadem need district qualification. It does not explicitly compare this tool against sibling tools, so it falls short of full alternative guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes beyond them by disclosing the server-side outer result limit (default 20, max 100) that applies even when SQL omits LIMIT, and the allowlist gate. It does not describe error behavior or the shape of returned rows, but for a read-only tool this is solid added 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?

The core statement is front-loaded and the body is compact bullets of constraints, with two reference links at the end. The phrase 'A complete bounded capture is required, never partial counts' is cryptic and costs a line without clearly earning it.

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 3-parameter SQL tool with no output schema, the description covers dialect, permitted table/columns, allowlisting, and result caps — enough to call it correctly. Remaining gaps are the role of the `limit` field and what the response looks like, which are secondary.

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 all three parameters (sql, limit, resource_id) rely on the description. It adds genuine meaning for sql (table name 'records', published column names, aggregates allowed) and for resource_id (must be allowlisted), but never explains the `limit` parameter or how it interacts with the enforced max of 100.

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 lead sentence gives a specific verb and resource: a bounded SELECT over records from an allowlisted CKAN resource, plus the SQLite dialect constraint. That is clearly a SQL-query tool, though the description never distinguishes it from the sibling istanbul_query_resource, so the agent must guess which one to use.

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 real preconditions (resource must be in CKAN_SQL_ALLOWED_RESOURCE_IDS) and exclusions (no writes, no arbitrary functions, no application DB), plus a directive that a complete bounded capture is required rather than partial counts. What is missing is explicit routing against the sibling query tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety behavior is fully covered elsewhere. The description adds only that the payload contains metadata and resources; it says nothing about what 'resources' concretely entails, whether the result can be large, or how invalid dataset ids are handled, so the added behavioral value is modest.

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

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

A single front-loaded sentence with no filler and no repetition of the title. It is efficient, though the brevity shades into under-specification given the undocumented parameter.

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 at least name the two return categories (metadata and resources), which is the minimum needed. But for a lookup tool it omits the identifier format, prerequisites, and failure behavior, leaving meaningful gaps.

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% for the single required dataset_id, so the description must carry the burden and does not. It never states the id format (numeric, slug, UUID) or where the id comes from (e.g., istanbul_search_datasets), which is the one piece of information an agent needs to invoke this correctly.

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 gives a specific verb (return) and resource (metadata and resources for one IBB dataset), which is far more informative than the title alone. It implicitly differentiates itself from list-style siblings like istanbul_search_datasets and row-extraction siblings like istanbul_query_resource, but it never names them, so the differentiation is left to inference.

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?

There is no explicit when-to-use or when-not-to-use statement and no mention of alternatives. The phrase 'for one IBB dataset' plus the required dataset_id only implies the usage pattern (you already know which dataset you want), leaving the agent to infer that istanbul_search_datasets is the prerequisite when the id is unknown.

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 covered. The description adds nothing beyond that — no note on whether it performs a network round-trip to a live DataStore, what happens with an invalid or unknown resource_id, or what shape the returned field schema takes. With annotations present the bar is lower, but this contributes zero extra 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?

One short, front-loaded sentence with no filler — but it is concise to the point of under-specification rather than efficiency, so it sits at minimum viable.

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

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

No output schema exists, so the description is the only place to convey what a "field schema" return looks like (column names, types, nullable flags), and it does not. Combined with an unexplained required identifier and no sibling routing, an agent lacks enough to call this confidently in the right situations.

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% for the single parameter resource_id, and the description does not compensate: it never says what a resource is, where the identifier comes from, or whether it is a DataStore resource slug versus a dataset-level identifier. For a 1-param tool the burden falls squarely on the description, and it is not met.

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 ("Return") and a specific resource ("DataStore field schema for a resource"), so an agent knows exactly what comes back. It does not differentiate from siblings like istanbul_query_resource or istanbul_get_dataset, which the rubric caps at 4.

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?

There is no guidance on when to call this versus istanbul_query_resource, istanbul_get_dataset, or istanbul_search_datasets, and no prerequisite stated (e.g. that resource_id must first be obtained from a dataset listing). The agent must infer the workflow entirely.

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

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

Adds substantial context beyond the annotations: no upstream request is made, missing/warming snapshots mean unavailable rather than empty, cache age is not publication age, and a loaded snapshot does not prove live service. These are exactly the interpretive pitfalls an agent needs.

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-loads what is inspected, then follows with tightly scoped caveats. Every sentence earns its place, with no repetition of annotations or title.

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 zero parameters, an existing output schema, and rich annotations, the description is complete. It covers purpose, non-behaviors, and interpretation risks without needing to explain return values.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly adds no parameter detail because none exist.

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

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

States a specific verb and resource: inspect local GTFS snapshot state, enumerated as load age, calendar validity, row counts, and skipped rows. The 'local' qualifier and the final caveat ('does not prove live arrivals') distinguish it conceptually from live transit siblings such as next_departures or transit_line.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes clear this is a local snapshot diagnostic and explicitly says no upstream request or refresh occurs, which implies when it is appropriate. However, it does not explicitly name alternatives or state when to prefer this over siblings like istanbul_health or istanbul_get_dataset.

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, non-destructive and openWorld, so safety is covered. The description adds no behavioral context of its own: it doesn't say what 'readiness' covers, whether it reflects downstream dependencies, or how quickly it responds.

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

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

A single short sentence, front-loaded and free of filler. It is efficient, though its brevity leaves the burden of explanation entirely unmet rather than genuinely earned by rich content.

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 and no parameters, the description is the only place to explain what a readiness result looks like (status flag, component list, error detail). It supplies none of that, so an agent cannot anticipate the response or act on it.

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

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

The tool takes zero parameters, so the baseline for this dimension is 4. There is nothing for the description to disambiguate.

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 concrete verb and resource: returns Istanbul MCP service readiness. That is clearly separable from the sibling tools, which all query city data, so the health-check scope is unambiguous. It stops short of naming the check explicitly (liveness vs. dependency readiness), which keeps it from a 5.

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?

There is no guidance on when to call this rather than a sibling, no mention of preconditions or typical scenarios such as diagnosing failures before retrying a data query. The agent must infer that this is a diagnostic endpoint from the word 'readiness' alone.

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

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

Annotations already cover safety (readOnly/idempotent/destructive=false), and the description adds real value beyond them: the data is static and weekly, coordinates are source points rather than geocoded market locations, and maps_url is a search link, not a precise pin. That preempts several likely agent misreadings. It says nothing about pagination or data freshness/update cadence, keeping it out of the 5 band.

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, front-loaded sentences with no filler: scope first, parameter format second, interpretation caveats last. The coordinates/maps_url sentence is slightly tangential but still earns its place as a usage caveat.

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

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

With an output schema present, return values needn't be described, and the key interpretive caveats are covered. The remaining gap is the undocumented `limit` parameter and district matching rules, which matters for a 3-parameter tool with no schema descriptions.

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 carries the burden. It does this well for `day`, enumerating accepted formats (Turkish/English weekdays, today/yesterday/tomorrow, ISO date), and implies `district`. But `limit` is never mentioned and `district` matching semantics (exact name? case-insensitive? Turkish characters?) are unstated, so compensation is only partial.

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 — returns the published weekly İBB market schedule — plus the optional scoping dimensions (district/day). This clearly separates it from siblings like istanbul_nearby or istanbul_query_resource, which cover 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 line 'Results are a static weekly schedule, not proof a market is open today' is an explicit when-not-to-rely-on-it caveat, which is strong guidance. It doesn't name a sibling alternative for live market status, so it stops short of the top band.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety behavior is covered. The description adds useful scope context by saying results are official counts/faults and not an accessibility guarantee, but it does not discuss auth needs, rate limits, pagination, or freshness of fault 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?

Two compact sentences: the first front-loads what is returned and its optional filters, and the second adds a clear scope disclaimer. No filler or repetition.

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

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

The tool is read-only per annotations and has no output schema, so the description should carry more weight for return shape and filtering behavior. It adequately says counts and fault details are returned, but the undocumented limit and lack of return structure or pagination details leave gaps for an agent invoking it with optional parameters.

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

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

Schema coverage is 0% for all four parameters. The description names three filters (line, station, equipment_type) but gives no format, accepted values, or examples, and omits the limit parameter entirely, leaving meaningful semantics undocumented.

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 action and resource: returns official Metro İstanbul equipment/total counts and current equipment fault details. The tool name suggests accessibility, but the description explicitly clarifies the narrower equipment/fault scope and adds a disclaimer, so an agent can distinguish it from a general accessibility guarantee, though not directly from siblings like transport_disruptions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Mentions optional filtering by line, station, or equipment type, which implies usage for narrowed lookups. However, it does not state when to choose this over sibling tools such as istanbul_transport_disruptions or istanbul_gtfs_snapshot_status, and no when-not guidance is given beyond the accessibility disclaimer.

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 the safety profile (readOnly, idempotent, non-destructive, open-world), and the description adds real behavioral context beyond them: district queries return parking only without distances, and district-only place names behave the same. It still omits return shape, radius behavior, and limit effects.

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, with the main purpose stated first and constraints following. The sentence 'District-only place names do the same' is somewhat redundant with the preceding district rule, but overall there is little waste.

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 six parameters, 0% schema description coverage, and no output schema, the description provides only partial coverage. It handles the trickiest mode-selection constraints but leaves important call-shaping details like radius_m default behavior, limit semantics, and returned content unexplained.

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 carry parameter meaning. It explains district/place/coordinates exclusivity and the Acıbadem disambiguation rule, but says nothing about lat, lon, limit, or radius_m, leaving half the parameters undocumented.

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 clear verb and resource: summarize mobility near a static place reference or coordinates. It does not explicitly distinguish the tool from siblings such as istanbul_nearby or istanbul_city_services_nearby, so it falls short of a 5.

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 useful input-mode guidance: district is exclusive with place/coordinates, district-only queries return parking only, and the tool is not address geocoding. However, it never says when to prefer this tool over nearby siblings, so alternatives remain ambiguous.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so the bar is lower; the description still adds meaningful caveats an agent could not infer — static layers return published locations not live status, pharmacy duty-end times are not guaranteed, and maps_search_url is address search rather than a verified pin. These are exactly the trust caveats that prevent misuse of the results.

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

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

The primary capability is front-loaded in the first sentence and the caveats follow in a compact block with no filler. The remaining lines read as an unordered list of disclaimers rather than being grouped by mode, which slightly hurts scanability but not length.

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

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

An output schema exists, so return-value description is not needed, but with eight optional parameters at zero schema coverage the definition should state at least the constraints for radius_m/limit and the lat/lon vs bbox vs district exclusivity. As written, an agent can call it but cannot confidently pick the right spatial arguments.

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 0%, so the description must carry parameter meaning, and it does clarify kind-dependent applicability (bbox/types only valid for city_feature) and what air_quality vs city_feature return. But it says nothing about limit, radius_m, or whether lat/lon must be paired, leaving three of eight parameters undocumented anywhere.

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 opening sentence gives a specific verb and resource ('Find city services by kind and coordinates, or parking/pharmacy by district') and even splits the two operating modes. It clearly separates the coordinate-based and district-based lookups, though it never names the overlapping sibling istanbul_city_services_nearby to disambiguate.

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 supplies real conditional guidance — bbox and types apply only to city_feature, and district lists are the alternative path without distances. However, it gives no guidance on when to pick this tool over its many near-identical siblings (istanbul_city_services_nearby, istanbul_mobility_nearby), leaving the main selection decision 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 covered externally. The description adds one genuinely useful behavioral fact — that the result is a join across three record sources, warning the agent the payload is composite rather than a raw dataset. It says nothing about result volume, missing-data behavior, or cost of the join.

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

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

A single front-loaded sentence with zero filler; the resource and its composition are stated immediately with no redundant restatement of the title.

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

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

No output schema and no annotation detail means the description must explain the returned structure, yet it does not say what fields a 'profile' contains, whether records are nested per source, or how district-only calls behave. For a three-source join with three undocumented parameters, this leaves the agent materially under-informed before 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?

Schema description coverage is 0%, so the description carries the full burden and provides nothing: it never explains that district is required, that omitting neighborhood yields district-wide results, or what limit governs (neighborhoods returned? records per source?). An agent must guess from bare field names.

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 ('return a joined neighborhood profile') and names the three source record types (social, building, earthquake scenario), which tells the agent this is a composite/aggregate endpoint. It does not explicitly contrast with siblings like istanbul_nearby or istanbul_datastore_query, but the resource is distinctive enough that confusion is unlikely.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: the profile is scoped per neighborhood, so an agent can infer it should be used when a location-level summary is wanted. There is no statement of when to prefer this over istanbul_nearby, istanbul_datastore_query, or the individual source endpoints, and no prerequisites or exclusions are given.

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

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

Annotations already declare readOnly/idempotent/non-destructive and open-world, so the description doesn't need to restate safety. It adds substantive behavior instead: results are scheduled times, never live ETA or proof of service, the search window is fixed at 24 hours, approximate spellings are labeled rather than treated as matches, and missing metadata stays null rather than being inferred. It does not mention pagination, ordering, or rate/coverage errors, 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?

Nearly every sentence carries operational information: mode separation first, then discovery workflow, then field provenance caveats, then time-window and exclusivity constraints. The only cost is structure—sentences are hard-wrapped across lines, so related clauses (e.g. 'The search covers 24 hours. stop_id and coordinates are mutually exclusive.') are visually split, which slows scanning slightly.

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 8-parameter, zero-schema-description tool with an output schema present, the description supplies the temporal semantics, mode workflow, coordinate-vs-id exclusivity, and data-provenance limits an agent needs to call it correctly. Return values need not be described because an output schema exists. The unaddressed radius_m and the absence of any guidance on combining line with coordinates are the only substantive omissions.

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?

With 0% schema description coverage the description must explain all 8 parameters, and it covers most: at (ISO datetime with UTC offset, defaults to now in Europe/Istanbul), stop_query/limit discovery mode, stop_id, lat/lon mutual exclusivity, and line (published route short name). radius_m is never mentioned, which is the one notable gap given coordinates are supported. stop_code/stop_desc/platform_direction_text are explained as output fields rather than parameters, which is still useful.

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 two distinct modes with specific verbs and resources: name-based GTFS stop discovery via stop_query, and published departures for a stop_id or coordinates. Explicitly warns 'This mode returns stops, NOT departures', which prevents the most likely confusion with a sibling transit tool. The distinction from other Istanbul tools is implicit but the naming and scoping are sharp enough for an agent to route correctly.

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 explicit when-to-use rules for each mode ('Use stop_query with limit only to discover stop_id candidates'), an exclusion ('never choose the first automatically', 'Same-name stops remain separate'), a workflow ('Ask the user to select a candidate ... then call with stop_id'), and hard constraints ('stop_id and coordinates are mutually exclusive', 'Outside-calendar queries are unavailable'). This is about as complete a routing guide as a two-mode tool can have.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered. The description adds useful method context ('datastore_search, not SQL') and mentions 'guarded filters and limits', but 'guarded' is never explained — no stated cap, error behavior, or cost of broad scans.

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 lines, purpose front-loaded, with the API reference link serving as a compact pointer to fuller docs. Slightly terse on the one point (limit) that most needs spelling out.

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?

A 3-parameter read tool with no output schema and full annotation coverage — so the bar is modest — but the description omits the return shape of datastore_search (records/fields/total) and the limit ceiling, both of which change how an agent calls it.

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 0%, so the description carries the burden; it does clarify that filter keys must match the resource schema, which is real semantic value. But limit goes undocumented (no default, no max, no behavior when null) and resource_id's sourcing (from get_dataset/istanbul_search_datasets) is left implicit.

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 (query) and resource (IBB CKAN DataStore records) and adds the mechanism ('datastore_search, not SQL'). However, it never distinguishes itself from the near-identical sibling istanbul_datastore_query, leaving the agent to guess which to call.

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?

'Field names come from the resource schema' implies a prerequisite workflow (call istanbul_get_resource_schema first) and 'not SQL' rules out a competing approach. But there is no explicit when-to-use vs the datastore_query sibling or when-not to use this tool at all.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the safety bar is lower. The description adds nothing beyond the one-line purpose – no note on search behavior, result scoping, or empty-result handling.

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

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

A single front-loaded sentence with no waste. Its terseness is a content gap, not a verbosity issue, so conciseness itself is fine.

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 3-param search tool with no output schema and no param docs, the description is too thin. It doesn't tell the agent what comes back (dataset list? IDs to feed into istanbul_get_dataset?) or how to use filters.

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 0%, so the description should carry the burden, yet it explains none of the three params. 'Search' loosely maps to `query`, but `limit` (max results?) and `formats` (allowed values like CSV/JSON?) are left completely ambiguous.

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?

Clear verb+resource: 'Search the IBB open data catalog'. But it doesn't distinguish from sibling catalog/datastore tools like istanbul_datastore_query or istanbul_query_resource, so it falls short of the 5 bar.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, no exclusions, and no mention of the alternative siblings (datastore_query, get_dataset). The agent must infer usage entirely.

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 only the 'citywide' scope qualifier — it says nothing about whether the index is live/real-time (relevant given openWorldHint), how frequently it refreshes, or what happens if traffic data is unavailable.

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

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

A single front-loaded sentence with zero filler. Nothing could be removed without losing information, and the scope qualifier is placed where it is read 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?

With an output schema present, the description needn't explain return values, and with zero parameters the schema burden is nil. The only meaningful gap is the absence of any statement about data recency or the fallback behavior when traffic data is stale, which matters for a live openWorld metric.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The implicit 'no parameters = always citywide aggregate' framing is consistent with the empty 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 ('Return Istanbul citywide traffic index'), which is unambiguous and names the scope ('citywide'). It does not explicitly distinguish itself from adjacent siblings such as istanbul_transport_disruptions or istanbul_metro_accessibility_status, so an agent must infer that this is the aggregate congestion metric rather than a disruption feed.

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 no when-to-use guidance, no exclusions, and never names an alternative sibling. The agent must derive the use case entirely from the tool name and the word 'index'.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds genuinely useful behavioral context: departures are planned main-terminal times, not live intermediate-stop ETAs, and limit applies only to that action. That is real value beyond the annotations, but return shape and freshness/staleness of schedule data are left unaddressed.

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, front-loaded sentences with no filler; the primary capability comes first and the caveats follow. The telegraphic phrasing ('limit applies only to departures') is terse but unambiguous.

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

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

An output schema exists, so return values need not be described, and the annotations cover the safety profile. Given three simple parameters, the remaining need is guidance on line_code format and the info-versus-departures distinction, which is the only real gap.

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

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

Schema description coverage is 0%, so the description carries the burden. It does map loosely onto the three enum actions via 'info, ordered stops, planned departures' and clarifies that limit applies only to departures. However, line_code format and units/bounds for limit are never explained, so the compensation is partial.

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 (Get) and resource (IETT line), and enumerates the three modes of content: info, ordered stops, planned departures. It does not distinguish itself from the close sibling istanbul_next_departures, which also covers departures, so an agent must infer the split from the 'planned main-terminal' vs 'live intermediate-stop' phrasing.

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 one explicit exclusion ('not live intermediate-stop ETA') and one explicit routing rule (cross-operator notices go to istanbul_transport_disruptions). It also scopes the limit parameter to departures only. It stops short of saying when to pick action=info versus stops versus departures, leaving that to the enum.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety and freshness profile is largely covered. The description adds only that results are 'current' and 'official', with no mention of what 'supported operators' excludes, no coverage of filter behavior, and no statement about how partial filters narrow results. That is modest added value over the annotations.

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

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

A single front-loaded sentence with no filler; the core purpose is stated immediately. It is efficient rather than padded, though the brevity comes at the cost of detail covered elsewhere.

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

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

The presence of an output schema and rich annotations relieves some burden, but with four optional free-form parameters at 0% schema coverage the description leaves the agent guessing how to construct a filtered query. For a discovery-style disruption feed, at least a note on filter values or defaults would be expected.

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?

All four parameters (line, mode, limit, operator) arrive with 0% schema description coverage, so the description carries the full burden. It gestures at 'operator' and implicitly 'line'/'mode' through the word 'transport', but says nothing about accepted values, format, whether filters are AND-combined, or what 'limit' bounds. This is a serious gap for a 4-parameter tool.

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 pairs a specific verb ('Return') with a specific resource ('current official disruptions and service announcements') and scopes it to 'supported transport operators', which separates it from siblings like istanbul_traffic_status or istanbul_water_status. It stops short of naming those siblings explicitly, so it is clear but not maximally differentiated.

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 offers no guidance on when to reach for this tool instead of istanbul_traffic_status, istanbul_water_status, or istanbul_next_departures. There are no exclusions, prerequisites, or usage contexts — the agent must infer everything from the name and one sentence.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: results carry fallback freshness, fault locations are approximate, and there is no restoration guarantee.

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

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

The description is front-loaded with the core purpose, followed by constraints, sibling routing, and data-quality caveats. It is compact and every sentence adds useful information without repetition.

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 rich annotations and an output schema, the description does not need to explain return values. It covers the main modes, key constraints, sibling alternative, and caveats; the remaining gap is incomplete documentation of parameters such as limit and min_occupancy.

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 carry parameter semantics. It clarifies district/fault_number exclusivity and that dam filters apply only to dams, which partially covers the six parameters, but it leaves limit undocumented and only implies dam_name/min_occupancy through the phrase 'dam filters.'

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

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

The description starts with a specific verb and resource: 'Get ISKI active faults ... or dam occupancy.' It also distinguishes the two query modes via district/fault_number versus dam occupancy, and explicitly points nearby fault queries to a sibling tool, so an agent can identify the tool's scope 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?

It gives explicit mode constraints ('Dam filters apply only to dams; fault_number is exclusive with district') and names the alternative for nearby faults: istanbul_nearby(kind="water_fault"). This tells the agent both when the tool applies and when to route elsewhere.

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