Mappit

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description goes further by disclosing the data source (OpenStreetMap), result ordering ('Nearest first'), and which attributes come back (address, opening hours, website, phone), which an agent cannot infer from annotations alone.

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

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

Front-loaded with the core action and scope in a single dense sentence, with examples inline. The trailing attribution ('Data © OpenStreetMap contributors') is licensing boilerplate rather than agent-relevant guidance, costing a small amount of space.

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 usefully tells the agent what fields to expect back and how results are ordered. Defaults, limits and accepted input forms are handled by the schema, so nothing essential is missing for a 5-parameter read-only search.

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 all five parameters and their defaults/limits are already documented. The description's restatement of q's flexibility (name/kind/cuisine) largely duplicates the schema, adding no syntax or edge-case detail beyond it.

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 (Find) and resource (businesses and landmarks near a place), plus the underlying corpus (14.9 million OpenStreetMap entries). This is clearly distinguishable from siblings like get_directions, get_location, and search_mappit without opening a schema.

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

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

The description implies when to reach for this tool (proximity search against a POI directory) and shows three query modes (name, kind, cuisine), but it never names an alternative or states when NOT to use it — e.g. versus get_directions for routes or get_location for a single place. Usage is inferable rather than explicit.

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=false, so the safety profile is fully covered. The description adds content-nature context (digest is 'as emailed to subscribers', weekly is 'analysis'), but nothing about pagination, archive size, or freshness limits beyond 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?

Two sentences, zero waste, and the two editions are defined before the parameter-recipe sentence. Every clause earns its place.

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

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

For a read-only retrieval tool with no output schema, the description covers what the editions are and how to reach the latest vs. the archive. Combined with 100% schema coverage and full annotations, an agent has enough 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 100%, so the baseline is 3, but the description adds the combination semantics the schema states only piecewise: omitting date and slug yields the latest edition, and list=true switches to the archive. It notably omits any mention of the 'kind' and 'detail' parameters, which the schema carries alone.

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 the resource precisely — Mappit's two editorial editions, the Daily Digest and the Week in Review — and characterizes each (top stories worldwide vs. weekly analysis). An agent can tell this apart from siblings like get_story or list_stories, though it never states an explicit verb and does not name a sibling it is not.

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 conditional guidance: omit date and slug for the latest edition, set list to true for the archive. That covers the main usage forks for a zero-required-parameter tool. It stops short of naming alternative tools or stating when *not* to use this one.

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 (readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false), so the bar is lower. The description still adds real value by disclosing the return payload (distance, time, steps, map link), the coordinate-format flexibility, and the openrouteservice/OpenStreetMap attribution, none of which annotations provide.

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 tightly written sentences front-load the core capability and then the input forms, with no filler. The trailing attribution is legally required boilerplate rather than waste, so size is appropriate, though it is not strictly agent-facing 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, the description carries the burden of describing results and does so by naming the returned fields (distance, travel time, turn-by-turn steps, map link). What an agent needs to call it correctly is present; only finer details like step/pagination limits are left to the schema.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters (from, to, via, mode, steps). The description reinforces the endpoint forms but adds no syntax or format detail beyond the schema, making the baseline 3 correct.

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 directions) and resource (routes between places), and names exactly what is produced: distance, travel time, turn-by-turn steps, and a map link. It is clearly distinguishable from siblings like get_location (single point) or find_places (discovery), so an agent can route to it 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?

The description establishes clear usage context by defining the supported modes and the accepted endpoint forms (town, business/landmark, street address, lat,lon), which tells the agent when this tool fits. It does not, however, compare itself to siblings or state explicit exclusions, so it stops short of full when/when-not 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, closed-world), so the bar is lower. The description adds genuine behavioral context beyond that: the temporal windows for each section (72-hour storylines, 30-day publisher coverage) and the fact that a lat/lon resolves to the nearest Mappit place. It does not discuss response shape or limits, but the recency windows are valuable disclosure.

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

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

Front-loaded with the purpose, then the section inventory, then usage examples and the sibling handoff. The long middle clause is dense but every element maps to a real returned section rather than filler. Slightly heavy for a single sentence, but nothing is 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?

With no output schema, the description carries the return-value burden and does so by detailing the sections returned and their recency scopes. Annotations cover the safety profile. It stops short of describing ordering, pagination, or the response envelope, which would complete the picture for a read tool.

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

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

Schema coverage is 100%, so the schema already documents all three params, giving a baseline of 3. The description earns above baseline by enumerating the sections that correspond to the `include` values (about, stories, threads, sources, radio_tv, stocks, conditions) and the overview content behind `detail`. It does not add syntax for `place` beyond what the schema states.

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

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

The description states a specific resource (a place's profile on Mappit) and enumerates exactly what it returns: overview, latest stories, active storylines, publishers, radio/TV, S&P 500 companies, conditions. It explicitly distinguishes itself from the sibling whats_happening, so an agent can route without inspecting either schema.

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

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

It gives concrete trigger examples ("tell me about Fort Sumner", "who covers the news in Boise?") and explicitly names the alternative tool and the condition that selects it: for ranked current news use whats_happening. When-to-use and the alternative are both spelled out.

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 openWorld=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: whole-world result ordering for air_quality (worst readings first) and weather (hottest), which an agent cannot derive from the schema or 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?

The opening is front-loaded and readable, but roughly half the text restates the layer enum already present in the schema's layer description, which is wasted space. The trailing sentence about world-wide ordering is useful but tacked on rather than integrated.

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?

All five parameters are documented in the schema, annotations cover the safety profile, and the description explains the layer taxonomy. With no output schema, the description could say more about the shape of returned pins/readings, but for a self-explanatory read tool this is close to 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 100%, so every parameter (date, layer, limit, place, radius_km) is already documented, and the baseline is 3. The description reinforces that 'place' can be omitted for the whole world, but that is already in the schema, and the ordering note is a result behavior rather than parameter semantics.

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 the resource (Mappit's live map layers) and enumerates the concrete layer values with their data sources (USGS, NASA FIRMS, Open-Meteo), so an agent knows exactly what this tool returns. It does not explicitly differentiate itself from siblings like whats_happening or get_statistic, which also surface live data, 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?

Usage is only implied through the layer enumeration; there is no explicit 'use this when' statement and no alternative sibling is named or contrasted. The reader must infer that this is the tool for map-layer data versus the digest/story/statistic 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?

Annotations already establish that this is a safe, read-only, idempotent, closed-world operation. The description adds some useful context by saying counts are current and topics are accepted by other tools, but it does not discuss freshness guarantees, token handling, or other behavioral limits beyond that.

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 and efficiently enumerates the main information returned. The final sentence slightly repeats the topic-list point, but overall it is compact and readable.

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

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

With no output schema, the description adequately explains the returned information: Mappit identity, version, counts, topics, and countries. It leaves `pulse` and `token` sections unexplained, but the schema documents those section names.

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 has 100% description coverage for the single optional `include` parameter, including valid sections and defaults, so the schema does the heavy lifting. The description does not mention the `include` parameter or explain how sections like `pulse` or `token` affect the result.

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 this is a metadata tool about Mappit itself, listing version, counts, topics, and countries. It distinguishes itself from search/list siblings by noting the topic list contains slugs other tools accept, though it does not explicitly name alternatives.

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 a clear use case: learn valid topics for other tools. It does not state when not to use it or name alternative metadata/digest tools, so it falls short of full when/when-not 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the upstream data sources, the fact that a recent series is returned alongside the value, and the default-to-latest period behavior.

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

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

It is a single dense sentence followed by a short clarifier, front-loading the resource scope before the return contents and the code conventions. Information-dense but every clause carries substance; it could be split for readability but nothing is 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?

With no output schema, the description correctly compensates by listing the returned fields (value, period, rank, US figure, source, licence, series) and the data providers. It lacks any note on error or missing-data behavior, which is the only real gap for a 4-parameter lookup tool.

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

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

Schema description coverage is 100%, so baseline is 3; the description goes slightly beyond by explaining where indicator codes originate (list_map_apps) and clarifying the interaction between indicator and topic for news shares, which the schema presents as independent properties.

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 precisely what is retrieved (one statistic for one country, US state, county or congressional district) and enumerates the returned content (value, period, rank, US figure, source, licence, series). It is far more specific than the title alone and implicitly separates itself from rank_regions, though it never names a sibling to sharpen the distinction.

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 a concrete prerequisite by routing the agent to list_map_apps for indicator codes, and explains the news_topic_share:<topic> vs. separate topic argument path. It stops short of an explicit when-not-to-use statement or a named alternative for multi-place ranking.

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 establish readOnly, idempotent, non-destructive behavior, so the bar is low. The description adds real domain context beyond them: found_by distinguishes a crawler from an AI search vendor, and also_carried_by signals syndication across outlets. It omits error behavior for an unknown id, which is the remaining gap.

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

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

Front-loaded with the essential framing ('One story in full') followed by a dense field inventory and a one-line instruction. The long enumeration is justified because no output schema exists, though the single run-on sentence could be trimmed 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?

With no output schema, the description carries the burden of describing the return shape and does so thoroughly, field by field. Only failure behavior (unknown or stale id) is left unaddressed for a simple one-parameter lookup.

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% and the schema already says the id must match 'exactly as another Mappit tool returned it.' The description's 'Pass a story id from another Mappit tool' largely restates that, so it adds only marginal meaning over structured data.

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

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

States a specific verb+resource ('One story in full') and enumerates exactly what the payload contains — headline, summary, publisher, link, publication time, location, found_by, storyline, also_carried_by. This clearly distinguishes it from list_stories (singular, full detail) without needing to open either schema.

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

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

The only guidance is 'Pass a story id from another Mappit tool,' which clarifies parameter provenance but not when to choose this tool over list_stories or how to obtain a valid id in practice. Usage is implied rather than stated with alternatives or exclusions.

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, and non-destructive, so safety is covered. The description adds real context beyond them: stories come newest-first and are paged, the analysis is conditional ('when it has one'), and it imposes a downstream attribution rule ('Attribute the analysis to Mappit'). It stops short of stating page sizes or auth requirements.

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 no filler, front-loaded with what the call returns before the usage instruction. The middle clause stacks several returned artifacts in one run-on list, but nothing is 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?

With no output schema, the description correctly carries the burden of describing the return shape (summary, paged stories, analysis sections) plus the conditional-analysis caveat. Given four params at full schema coverage and clear annotations, only minor details like default page size are left implicit.

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 id, limit, cursor and detail are already documented, making 3 the baseline. The description only reinforces the id's provenance and hints at pagination via 'paged'; it adds no format or syntax detail the schema lacks.

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 ('One storyline') and enumerates the payload it returns: summary, stories, and the AI analysis. The word 'thread'/'storyline' plus the returned fields distinguish it cleanly from get_story, list_stories, and get_digest. An agent can select it without opening the schema.

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

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

Explicitly tells the caller where the required id comes from: 'Pass an id from list_threads, whats_happening or search_mappit.' That names the concrete alternative tools that generate valid inputs, which is the main failure mode for an id-taking 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, and destructiveHint=false, so the safety profile is covered. The description still adds real value by disclosing the return shape (indicator code, levels, time grain, source, licence, link) and the composite code convention for news topics — content an agent cannot get from the schema. It does not mention result size or whether the optional app filter alters the payload.

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 the resource name and domain coverage, then the return contents, then the call-to-action. The enumeration of app categories is dense but does real work by telling the agent whether its topic area is covered.

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 carries the return-value burden and does so (views, codes, levels, grain, source, licence, link). It also supplies the cross-tool relationship that makes the output actionable. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100% and the single `app` parameter is already documented, so the baseline is 3. The description goes slightly further by illustrating what an app/view code looks like, which helps an agent infer the values the `app` key accepts, though it never states that the parameter maps to that code.

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 (lists) and resource (each Map App's views) and immediately characterizes the domain coverage. It explicitly separates itself from siblings by naming get_statistic and rank_regions as the consumers of the indicator codes it exposes.

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

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

Gives a concrete trigger — use it to learn the indicator codes that get_statistic and rank_regions require — and shows the code format via the news-topic example ("news_topic_share:world-conflict"). This is explicit when-to-use with named downstream alternatives rather than implied context.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower; the description adds pagination behavior ('Returns a cursor for the next page'), the newest-first default, and the 'crawler' source meaning. It does not describe the shape of returned stories, but with no output schema the cursor/paging disclosure is the key behavioral fact and it is stated.

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

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

Front-loaded with purpose, scope and ordering in the first clause, then examples, filters, and the sibling routing last. Dense but every clause carries mapping value; slightly longer than strictly necessary due to the quoted example phrases.

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-optional-param, no-required-param tool with no output schema, the description supplies the ordering default, the paging contract via cursor, and the alternative tool. The only gap is it doesn't hint at what a story record contains, though paging and routing — the parts an agent must know to call correctly — are covered.

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 all 8 parameters including defaults and limits are already documented in the schema; the description only narrates filters ('time window, topic, language, and source crawler') plus example mappings. Baseline 3 is appropriate since the schema does the heavy lifting and the description adds no syntax beyond it.

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 ('Page through Mappit's stories'), the scope (place, country, whole world), the default ordering ('newest first'), and an alternate sort ('trending'), then names the sibling search_mappit as the tool for word/meaning lookup. An agent can distinguish this from search_mappit and whats_happening without opening a schema.

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

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

Gives concrete invocation scenarios ('all the news from Kyiv this week', 'more stories' after whats_happening, stories on one topic) and an explicit exclusion with the alternative: 'To find stories by words or meaning, use search_mappit.' When-to-use and when-not-to-use are both present.

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, and destructiveHint=false, so safety is covered. The description still adds non-obvious behavior: results are ranked as on the Threads page and each entry aggregates multiple stories, plus pagination via cursor and the 72h default window. It stops short of describing return shape or rate limits.

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 tight sentences that lead with the resource and its ranking, then the optional filters, then sibling routing. No filler, though the parenthetical examples make it slightly denser 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 no output schema, the description still conveys what a returned item represents (a storyline grouping many stories around one event) and its ordering. Combined with 100% schema coverage and rich annotations, an agent has everything needed 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 100%, so all four parameters (limit, topic, cursor, window) are already documented with defaults and accepted formats. The description only echoes 'optionally one topic or a time window' and adds no syntax, format, or interaction detail 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?

States a specific resource ('The storylines Mappit is following worldwide'), the ranking semantics, and what each item contains ('Each groups many stories about one developing event'), with concrete examples. An agent can distinguish this listing tool from get_thread (one storyline) without opening a schema.

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

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

Explicitly routes to alternatives: 'Use get_thread for one storyline's stories and Mappit's analysis; whats_happening gives the storylines around one place.' That names both the when-to-use and the when-to-use-something-else conditions.

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, not open-world). The description adds real behavioral context beyond that: each returned value carries its own period, and the answer names the source and licence, which tells the agent to expect provenance metadata and potentially mixed periods. It does not discuss rate limits, error conditions, or pagination beyond what the schema states, keeping it at a solid 4.

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 what gets ranked and by what, then scope, then provenance and code-sourcing. Dense but every clause carries information; only the parenthetical topic restatement is mildly redundant with 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?

There is no output schema, so the description must characterize returns — it does so by stating that values carry their period and that the source and licence are named. Combined with the annotation-covered safety profile and fully documented schema, an agent has enough to invoke correctly; only result-shape details (e.g., ordering guarantees, empty-result behavior) are absent.

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 would be 3. The description goes further by explaining the interplay between indicator and topic ("news_topic_share:<topic>", or pass topic separately) and by naming list_map_apps as the source of valid indicator codes, adding meaning beyond the per-property schema text.

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 (rank) and resource (countries/US states/counties/congressional districts) drawn from a named data source, and scopes the ranking to a single indicator. An agent can immediately distinguish this ranked-list tool from siblings like get_statistic or find_places 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 clear context: ranking over the latest or a chosen period, optionally narrowed by within, and it routes the agent to list_map_apps for indicator codes. It also gives an explicit alternative form for news-topic indicators (indicator carries the topic or pass topic). It stops short of naming a sibling as the wrong tool or stating exclusions, so it is a strong 4 rather than a 5.

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 openWorld=false, so safety is covered. The description adds real behavioral context beyond that: what each mode actually searches, the default full-archive scope, and the narrowing effect of window/place. It stops short of describing result ordering, result shape, or cost/rate behavior, which no output schema covers either.

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 tight sentences, front-loaded with the core verb and the mode split, then scope, then the sibling hand-off. The clause about reading the whole archive and optionally limiting to one place lightly restates the window/place defaults already in the schema, which is the only small 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 6-parameter search tool with rich annotations, the description covers modes, default scope, narrowing options and an alternative tool. With no output schema, the one remaining gap is what a result actually looks like (a story vs. thread vs. location, ordering, per-kind limits), but nothing required for a correct call is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds meaning the schema does not: it explains what 'semantic' does relative to 'keyword' with an example query, enumerates the entity kinds keyword mode reaches, and clarifies the window default in behavioral terms ('reads the whole archive'). It does not elaborate on limit or place syntax beyond what the schema already says.

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

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

States a specific verb+resource ('Search Mappit') and immediately disambiguates the two operating modes with concrete scope for each (keyword covers stories, storylines, places, businesses, pins, collections; semantic covers only stories and storylines). It also names a sibling, whats_happening, so an agent can tell the two apart without opening a schema.

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

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

Gives explicit mode-selection guidance with a worked example ('tenants organizing against rent increases') for when semantic is the right choice, states the default behavior (whole archive unless a window is given), and routes to the alternative tool for a specific need: 'For the latest news in a place, use whats_happening.'

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, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the return payload structure and the source_url/url linkage on each story — important since there is no output schema. It stops short of mentioning auth needs, rate limits, or latency.

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

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

Front-loaded with the routing directive, then payload contents, then the exclusion — a sensible order with no wasted sentences. It is on the longer side and the run of four parallel example questions is slightly heavier than needed, but each element earns its place.

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

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

With no output schema, the description correctly takes on the burden of describing what comes back and how deep the response goes. Annotations cover safety, so the remaining gap is operational (pagination or result capping on the storylists), which is a minor omission for an otherwise complete definition.

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 schema already documents place formats, topic slugs, detail defaults, window values, language codes, and radius defaults. The description's example queries illustrate place scope implicitly but add no format or constraint details beyond the schema, so the 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?

Names a specific verb and resource (retrieve news for a place or the world) and enumerates exactly what comes back: ranked top stories, storylines, live conditions, and a place profile. It also explicitly distinguishes itself from get_location, so an agent can route without opening either schema.

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

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

Opens with an explicit priority directive ("Use first for the news in a place or the world") and supplies four example queries that map to distinct parameter configurations. It names the alternative (get_location) and the exact condition that selects it ("what a place is rather than its news").

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