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

With no annotations, the description carries the full burden and does so: it discloses result caching keyed on search parameters, the resource_id cache key contract for pagination, and a concrete cost/latency tradeoff (road_radius_km=0 skips OSMnx network downloads from Overpass API). It also explains that max_locations applies before pagination, avoiding a common misuse.

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 usage guidance, then a fast-mode callout, then a conventional Args block — well structured and scannable. The 'Returns' section partly repeats what the output schema already provides, so a little length is not strictly earned.

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 14-parameter, no-annotation, synchronous search tool with pagination and caching, the description covers invocation, cost tradeoffs, pagination stability, and output shape. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it documents all 14 parameters — bounding box, pagination, elevation prominence, road radius, network type, the popularity heuristics and their radius, and db_config_path. Non-obvious semantics such as 'Set to 0 to skip road checks' and 'before pagination' add meaning the bare schema cannot convey.

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 ('Analyze a geographic area for suitable stargazing locations') and immediately contrasts itself with the async sibling ('Do not use when: the search needs background polling/cancellation'), which is exactly the distinction from submit_area_analysis. An agent can route correctly 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?

Explicit 'Use when' / 'Do not use when' blocks name the conditions (synchronous place candidates, fixed regional query) and the alternatives (submit_area_analysis for background work, plan_stargazing_session for complete night plans). The follow-up line even tells the agent how to fetch further pages.

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?

Goes well beyond the annotations: it discloses that cancellation is logical (not physical), that a running provider call keeps its execution slot, that late results are discarded rather than published, and that terminal states are unchanged by re-invocation. That is exactly the non-obvious behavior an agent needs before invoking a mutation.

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?

Labeled lines (Use when / Do not use when / Requires / Returns / Follow-up) make it skimmable and front-load the core action. It is somewhat longer than strictly necessary, with mild redundancy between the opening sentence and the Returns line.

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

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

For a single-parameter mutation with an output schema, it covers provenance, idempotency, side effects, and the confirmation workflow. Nothing an agent needs to call it safely and correctly is missing.

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

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

Schema coverage is 0%, so the description must carry parameter meaning; it specifies that task_id comes from submit_area_analysis and must be from the same server runtime, which is a real constraint the schema lacks. It does not state the format or what happens with a stale/invalid id, so it falls short of full compensation.

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

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

States a specific verb and resource ('logically cancel queued/running area work and discard its late results') and contrasts it with neighboring operations such as deleting cached data. An agent can distinguish it from get_area_analysis_task or submit_area_analysis without reading 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?

Provides explicit 'Use when' and 'Do not use when' clauses plus a named alternative domain ('another domain's operation'), and names the prerequisite tool (submit_area_analysis) and the confirmation follow-up (get_area_analysis_task). Routing is fully determined.

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 read-only, idempotent, and non-destructive, yet the description adds behavior they cannot express: results come from cache, no silent recomputation occurs, the resource_id is version-checked against the task's publication version, and expired results surface as TASK_RESULT_EXPIRED. That is the kind of failure-mode and staleness context an agent cannot infer 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?

Labeled sections (Use when / Do not use when / Requires / Returns / Follow-up) front-load the routing decision and waste little space. The Returns line partially duplicates the already-present output schema, which is the only real 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 paginated cache-read with an output schema, an agent has everything needed: precondition (task succeeded), parameter constraints, pagination path, staleness check, and the recovery action on expiry. No behavioral question is left open before invocation.

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

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

Schema coverage is 0%, so the description must carry the load: it states task_id must belong to a successful task and constrains page >= 1 and page_size >= 1, which the schema does not. It stops short of giving any bound or default rationale for page_size, leaving some semantics to inference.

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?

"Page a successful area task's existing cached result without recomputing" names a specific verb (page), a specific resource (a cached area-analysis result), and its defining constraint (cache-only, no recomputation). It is immediately distinguishable from siblings like get_area_analysis_task or submit_area_analysis.

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?

"Use when: get_area_analysis_task reports succeeded..." and "Do not use when: the task is queued/running and you only need to poll its state" give an explicit inclusion and exclusion with the alternative named. The follow-up line further routes to get_area_analysis_task for state and to resubmission on TASK_RESULT_EXPIRED.

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?

Goes well beyond the annotations: discloses that running progress is unknown, that success does not guarantee the result cache still exists, that the task_id is only valid in the same server runtime, and how to recover on TASK_RUNTIME_CHANGED. These are non-obvious operational traits an agent could not infer from readOnlyHint/idempotentHint.

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, then organized into Use when / Do not use when / Requires / Returns / Follow-up blocks. Every sentence carries actionable information, with no filler or 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?

For a single-parameter polling tool this is complete: it covers prerequisites, what the snapshot contains, known limitations of the state signal, and the next step. Even though an output schema exists, the caveats about unknown progress and cache expiry are exactly the gaps structured output could not convey.

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 the burden; it specifies the parameter's provenance (returned by submit_area_analysis) and a runtime constraint (same server runtime), which is real meaning beyond 'task_id: string'. It stops short of describing the ID's format or lifetime beyond the runtime caveat.

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 ('Poll an area task's state, deadline, failure, and normalized request') and enumerates exactly what fields the snapshot covers. This cleanly separates it from submit_area_analysis, get_area_analysis_result, and cancel_area_analysis_task without the agent needing to open any 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?

Explicit 'Use when' and 'Do not use when' clauses, including the negative guidance not to submit a new job merely to poll and not to use it for result pages. It also routes to the correct siblings ('get_area_analysis_result after success; cancel_area_analysis_task if unwanted') and gives a recovery path for TASK_RUNTIME_CHANGED.

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

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

With no annotations at all, the description carries the entire burden and does most of it: it discloses that recommendation_score is relative not probabilistic, that _meta.status=success can still carry warnings, that missing-weather candidates are zero-weight placeholders rather than bad-weather facts, and that night_window is civil (-6°) not astronomical (-18°) darkness. The remaining gap is operational — nothing says whether this is read-only, whether it is expensive/slow (db_config_path and road_radius_km hint at heavy geospatial computation), or what permissions it 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?

Well front-loaded: purpose, use-when, do-not-use-when, requires, returns, then caveats. Nearly every line carries decision-relevant information, though the block of return-value caveats is lengthy and partly overlaps territory an output schema already covers.

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?

Return-value semantics are covered far beyond what the output schema provides, so an agent knows how to interpret degraded results. But for an 18-parameter, annotation-free tool, the description leaves the majority of tuning parameters semantically undefined, which is the gap most likely to cause a wrong invocation (e.g., misusing observation_style or the three different limit parameters).

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

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

Schema description coverage is 0% across 18 parameters. The description only restates the six required ones ('south/west/north/east bounds, observation time, and timezone'), which the schema's required array already conveys. The twelve optional parameters — observation_style, weather_provider, candidate_limit vs max_locations vs target_limit, avoid_popular_spots, prefer_quiet_at_night, network_type, min_height_diff — get no meaning, valid values, or default rationale anywhere, so an agent must guess at all the ranking-affecting knobs.

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 — 'Create a composite stargazing plan for a region and time' — and immediately scopes it as bbox-first, night-scoped, and ranked. It explicitly names the siblings it is not (plan_stargazing_session, get_multiday_stargazing_plan), so an agent can distinguish it without opening any 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?

Contains an explicit 'Use when' clause, an explicit 'Do not use when' list with four named exclusions (new intent-based integration, place-name input, multi-night comparison, weather-only), and a 'Follow-up' line routing to the two preferred alternatives. This is the full when/when-not/alternative triad.

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

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

No annotations are provided, so the description carries the disclosure burden and does a good job stating required inputs, time format, timezone requirements, and the returned data structure. It could be slightly stronger by explicitly noting that this is a pure calculation with no side effects, but the behavior is otherwise clear.

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

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

The description is well structured and front-loaded: purpose first, then usage boundaries, requirements, follow-ups, arguments, and return shape. The sections are compact and each adds useful information without 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 the tool's complexity, five required parameters, lack of annotations, and available output schema, the description is complete. It covers purpose, usage boundaries, all parameter meanings, and the return structure sufficiently for an agent to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must compensate for all five required parameters. It documents each one, including examples for celestial_object, units for lon/lat, the exact time string format, and that time_zone is an IANA timezone.

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

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

The description uses a specific verb-resource pair: calculate altitude and azimuth angles for a celestial object. It clearly distinguishes the tool from siblings by saying it returns one named object's position rather than a list, events, forecast, or full observing plan.

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 explicitly states when to use the tool, when not to use it, and which alternative sibling tools to use for rise/set events, nightly targets, and complete observing decisions. The guidance is concrete and actionable.

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

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

With no annotations, the description carries the full burden and does well: it explains the two event_scope behaviors (calendar-day lookup vs independent next rise/set rolling into following days), lists prerequisites, and notes return keys. Gaps remain around degenerate cases (circumpolar objects, no rise/set) and error behavior, so not 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?

Structured with labeled sections and front-loaded purpose plus when/when-not. Slight redundancy: the Args and Returns blocks largely restate schema/output-schema content, but each remains brief and harmless.

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?

Output schema exists, so the "Returns" note is optional; parameters are fully documented and alternatives are named. Still missing edge-case behavior (objects that never rise or set, validation bounds on lat/lon), which would complete a calculation tool with no annotations.

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 compensate and does: it gives the time format ("YYYY-MM-DD HH:MM:SS"), the IANA timezone string, degrees for lon/lat, example object names ("sun", "moon", "andromeda"), and a clear default/semantics for event_scope. This is meaningfully richer than the bare 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 ("Calculate the rise and set times of a celestial object") and distinguishes itself from siblings by naming get_celestial_pos for position and plan_stargazing_session for observing windows. 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?

Explicit "Use when" / "Do not use when" sections name the alternative (continuous observing window or complete night plan) and the required inputs. Nothing is left to inference about when this tool is the right choice.

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

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

With no annotations, the description carries the full behavioral burden. It states required inputs and return keys, but it does not disclose coordinate frame conventions, altitude/azimuth units, error behavior, or confirm read-only safety beyond the 'Get' verb.

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 organized into purpose, use/do-not-use, requirements, follow-up, args, and returns. Every sentence serves a clear selection or invocation purpose with no padding.

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 the full input set, usage boundaries, and return structure, and an output schema exists. However, it omits some invocation-relevant conventions such as longitude/latitude sign convention and output altitude/azimuth units.

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

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

Schema description coverage is 0%, so the description must compensate and does: it documents all five required parameters, including examples for constellation_name, degrees for lon/lat, the time string format, and IANA timezone. This is substantially more than the schema alone provides.

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

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

The description states a specific verb and resource: 'Get the position (altitude/azimuth) of the center of a constellation.' It also distinguishes the scope from adjacent needs by noting it is not for identifying which constellation contains arbitrary coordinates or choosing individual observing targets.

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 'Use when' and 'Do not use when' guidance, plus follow-up tools for related observing tasks. The exclusion for identifying a constellation from arbitrary coordinates is clear, but it does not name a specific alternative tool for that case.

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

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

With no annotations, the description carries the behavioral burden and does well: it says there are no inputs, clarifies that 'local' means the server environment, and describes the return shape. It does not explicitly state read-only/no side effects, but 'Retrieve' strongly implies that for this simple tool.

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

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

Front-loaded with purpose, then organized into Use when / Do not use when / Requires / Follow-up / Returns. Every section adds useful routing or behavioral context without 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?

For a no-parameter datetime tool, the description covers purpose, appropriate and inappropriate use, input expectations, the key semantic caveat, follow-up behavior, and return structure. An output schema exists, but the description remains complete without relying 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 has zero parameters, and the description correctly states 'no inputs.' Per the zero-parameter baseline, this is adequate and leaves little else to explain.

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: retrieve the current datetime and timezone. It also disambiguates the meaning of 'local' as the server environment rather than the user's observing site, which separates it from celestial/session-planning siblings.

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

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

Provides explicit 'Use when' and 'Do not use when' guidance, plus a follow-up warning not to infer observing-site timezone from this result. The boundary against remote-site timing and plan_stargazing_session usage is clear.

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

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

With no annotations, the description carries the burden and does disclose the key conditional behavior: lat/lon are optional, and supplying both unlocks local altitude, azimuth, moonrise, and moonset. It does not cover failure modes such as invalid timezone strings or out-of-range coordinates, which would be needed for 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?

The 'Use when / Do not use when / Requires / Follow-up' block is front-loaded and dense with actionable content. However, the Args and Returns sections largely restate the input schema and output schema, so some of the closing text does not earn 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 four-parameter read tool with an output schema, the description covers inputs, conditional local-position behavior, exclusions, and next steps. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 0%, and the description fully compensates: it gives the exact time format "YYYY-MM-DD HH:MM:SS", specifies an IANA timezone string, marks lat/lon as optional degrees and states the condition under which they matter. Every parameter is documented with more precision than a bare 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 (Moon phase and position) and immediately scopes what it covers: illumination, phase, and observer-local position. It explicitly distinguishes itself from siblings that rank sites or assess target suitability, so an agent can choose it without opening other schemas.

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

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

Provides an explicit 'Use when' and 'Do not use when' pair, names the prerequisites (time, timezone, both lat and lon for local results), and routes follow-ups to get_telescope_targets and plan_stargazing_session. Alternatives and exclusions 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?

With no annotations, the description carries the full burden and does so thoroughly: it flags that recommendation_score is a relative ranking rather than a threshold, that _meta.status=success can still carry per-night errors/warnings, that missing night-hour coverage means unknown rather than clear, and that civil darkness (-6°) is not astronomical darkness (-18°). These are non-obvious interpretation traps an agent would otherwise get wrong.

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 label-based structure (Use when / Do not use when / Requires / Returns / Follow-up) is well front-loaded and each sentence carries distinct information. The Returns block is dense but every clause is a caveat that prevents misreading; only minor tightening is possible.

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, yet the description still usefully summarizes the shape (data.query, per-night plans, best night, summary) and the caveats around it. Requirements, scope limits and follow-up routing are all covered; the only real gap is the unexplained optional tuning 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% across 19 parameters, yet the description only explains the four bbox bounds, start_date, time_zone and an optional night count. Twelve tuning parameters — network_type, target_limit, max_locations, road_radius_km, candidate_limit, min_height_diff, weather_provider, observation_style, avoid_popular_spots, popularity_radius_km, prefer_quiet_at_night, db_config_path — receive no semantic explanation anywhere, so the agent must guess their effect and valid ranges.

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 pair and resource: 'Compare one to seven consecutive nights and recommend the best night and place.' It also names the sibling tools it would be confused with (plan_stargazing_session, get_best_stargazing_plan) and what each is for, so an agent can disambiguate without opening schemas.

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

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

Explicit 'Use when' / 'Do not use when' blocks list the positive trigger (an existing bbox-first integration, 1-7 consecutive nights) and the exclusions (new intent-based integration, nonconsecutive dates, >7 nights, background task status). Alternatives are named in the Follow-up line.

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

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

With no annotations, the description carries the full burden and does it well: it discloses that deep_sky.score sorts ascending and must not be compared to telescope suitability_score (descending), that transit_alt is an estimate at scoring time rather than a solved meridian transit, and that night_window is civil darkness (-6°) not astronomical (-18°). It is silent on failure modes, however — invalid time/timezone handling, high-latitude cases where no civil darkness occurs, and whether the call has any cost — which is a real gap for a zero-annotation tool.

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

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

Front-loaded with purpose, then labeled Use/Do-not-use/Requires/Interpretation/Follow-up sections that scan quickly. The closing 'Returns' block largely restates what the output schema already declares, so that section is the one part that does not fully earn its 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?

For a 5-parameter tool with no annotations and a rich output schema, the description covers everything an agent needs to call it correctly: when to use, when not to, required inputs, argument formats, scoring-direction pitfalls, and next-step routing. Return-value structure is correctly left to the output schema.

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

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

Schema description coverage is 0%, so the description must compensate and it does: it documents all five parameters including the 'YYYY-MM-DD HH:MM:SS' format for time, the non-obvious caveat that a bare date means local midnight and may fall into the previous evening's night, IANA format for time_zone, and the default of 20 for limit. This is substantially richer than the bare schema types.

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

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

States a specific verb and resource ('Get a curated list of best objects to view for the night') and immediately bounds the scope with an explicit exclusion ('not telescope-specific target matching or regional site selection'). An agent can distinguish it from get_telescope_targets, plan_stargazing_session, and get_shooting_plan without opening any 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?

Uses explicit 'Use when' / 'Do not use when' clauses and names the prerequisite state ('place and night are known'). The 'Follow-up' line routes to three named siblings with the condition that selects each (known optics, imaging schedule, place/night still undecided).

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

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

No annotations, so the description carries the full burden and does it well: it discloses the pipeline composition, that target altitude is reported at civil dusk rather than the requested clock time, that scheduling uses a -6 degree civil-dark window rather than -18 degree astronomical darkness, and that weather/access/obstructions are NOT validated. It also pre-empts misreading empty slots as an all-night imaging commitment.

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 and the use/do-not-use routing, then caveats, then returns. Every section earns its place except the multi-line Returns block, which largely restates the existing output 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?

An output schema exists, so return values needn't be explained, yet the description still supplies the interpretive context an agent actually needs: which pipeline it wraps, the civil-dusk vs clock-time discrepancy, the -6 degree dark window, and the unvalidated factors.

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% across 16 parameters, and the description only names the four required inputs plus a vague grouping of 'optional sensor, optical, and minimum-altitude settings'. Non-obvious knobs such as limit, mount_type, filter_type, barlow_factor/reducer_factor and central_obstruction_pct get no semantic explanation, so it only partly compensates for the coverage gap.

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

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

Specific verb+resource ('Generate a single-night astrophotography shooting plan') with the composition stated explicitly: it runs match_telescope_targets then generate_shooting_schedule and returns targets + moon + timed slots in one response. That immediately distinguishes it from get_telescope_targets and the multi-night/stargazing planners.

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

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

Explicit 'Use when' (optics, place and night fixed) and 'Do not use when' (still choosing a site, comparing nights, only needing target ranks), with the alternative sibling named. The Follow-up line routes to get_telescope_targets and plan_stargazing_session for the excluded cases.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it states required inputs, interpretation caveats for altitude/azimuth timing, null rise/set semantics, and that suitability_score is a heuristic rather than weather clearance. It also explains that missing photometry means unknown rather than a visibility error.

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

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

The description is well structured and front-loaded with Use when / Do not use / Requires / Follow-up guidance. However, the Returns block substantially restates the output schema and makes the definition longer than strictly necessary, even though the interpretive notes within it are useful.

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

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

For a complex 15-parameter tool with no annotations and no schema descriptions, the definition is complete: it covers purpose, usage boundaries, required and optional inputs with units, alternatives, follow-ups, and return-field interpretation. The existing output schema means the description does not need to carry the entire return structure, but its added timing and null-value semantics are valuable.

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%, but the description documents all 15 parameters in the Args section, including optional fields, examples, units, enum-like values for filter_type and mount_type, defaults, and the 0-50 range for central_obstruction_pct. This fully compensates for the schema's lack of parameter descriptions.

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

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

The description states a specific verb and resource: recommend astrophotography targets for a telescope setup and return a ranked list of deep-sky imaging targets. It also distinguishes the tool from naked-eye targeting, timed scheduling, and site comparison, so an agent can identify its role among siblings.

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

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

It explicitly names when to use it, when not to use it, and alternatives such as plan_stargazing_session and get_shooting_plan. Follow-up guidance is also provided for timed slots, site comparison, and altitude at a specific clock time.

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

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

With no annotations, the description carries the behavioral burden. It discloses that the tool takes no inputs, discovers tools rather than performing observing analysis, and returns a dict with 'data' and '_meta' keys. It does not mention permissions or rate limits, but for a no-input discovery tool the key behavioral traits are covered.

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 structured and front-loaded, with clear sections for usage and returns. It is slightly verbose but every sentence supports correct tool selection or invocation.

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 this is a zero-parameter discovery tool with an output schema, the description is complete: it explains inputs, usage boundaries, follow-up, and return structure. An agent should be able to call it correctly without additional context.

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

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

The tool has zero parameters, so parameter semantics are inherently simple. The description appropriately states 'no inputs' rather than inventing parameter details.

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

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

The description states a specific verb and resource: 'Get metadata for all registered MCP tools.' It also distinguishes this tool from standard MCP tools/list discovery, making the purpose clear relative to sibling discovery behavior.

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 explicitly provides when to use, when not to use, required inputs, and a follow-up path. The guidance distinguishes this catalog tool from business/analysis tools and from standard client-side discovery.

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

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

With no annotations, the description carries the full burden and does: it discloses the geocoding cascade (offline China gazetteer → Photon → Nominatim), multi-provider aggregation with graceful fallback, that Open-Meteo needs no API key but network/provider failures are possible, and how to read providers/source for provenance. It also warns that missing or out-of-horizon hours are unknown rather than clear, and that forecasts are predictions — exactly the failure semantics 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?

Well front-loaded: purpose, then when/when-not, then requirements, then follow-ups, then interpretation notes. There is some duplication — the 中文地名提示 block and the trailing Args section repeat the same full-administrative-name guidance already given in 'Requires', so a few lines could be dropped without information loss.

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

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

For a 2-parameter tool with no annotations and no output schema, the description covers everything an agent needs: input naming rules, provider modes, fallback and failure behavior, and the return shape ('data'/'_meta' on success, 'error'/'_meta' on failure). The interpretation guidance on summary.current/daily/hourly closes the last 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 coverage is 0%, so the description must compensate and does: place_name is documented as requiring unambiguous full administrative names with concrete CJK examples ('浙江省安吉县' rather than 2-3 character short names), and provider is documented with its enumerated modes (all/qweather/open-meteo/wttr) even though the schema declares no enum. This adds substantial meaning beyond the bare schema types.

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 first line states a specific verb (获取/get) plus a compound resource (current + hourly + daily weather) and the resolution method (by place name). The follow-up line explicitly names get_weather_by_position as the coordinate-based sibling, so an agent can route between the two 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?

Explicit 'Use when' / 'Do not use when' pair covers both the positive trigger (place name in hand) and the two exclusions (exact coordinates, need for a complete observing decision). Follow-up names the concrete alternatives (get_weather_by_position, plan_stargazing_session) with the condition that selects each.

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

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

With no annotations, the description carries the full burden and does so: multi-provider aggregation with graceful fallback, Open-Meteo needs no API key, network/provider failures possible, and field semantics for summary.current/daily/hourly. It further warns that missing or out-of-horizon hours are unknown rather than clear, and that forecasts are predictions with uneven provider coverage.

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

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

Front-loaded structure is excellent: purpose, Use when, Do not use when, Requires, Follow-up, then interpretation notes. Slightly long, and the Args block partly restates what the schema already shows, but no sentence is wasted given the absence of annotations and output schema.

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

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

For a 3-param weather tool with no annotations and no output schema, the description covers return shape (data/_meta vs error/_meta), provenance/failure inspection, and forecast interpretation caveats. Nothing an agent needs to call or interpret it correctly is missing.

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

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

Schema coverage is 0%, so the description must compensate. It enumerates the provider modes (all/qweather/open-meteo/wttr), which the schema does not (no enum, just a string default), adding real meaning. lat/lon are only labelled 纬度/经度, which is trivially inferable, so this is strong but not fully compensatory.

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

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

States a specific verb and resource with scope: fetch consolidated weather (current + hourly + daily) by coordinates. The sibling get_weather_by_name is implicitly contrasted via the 'Use when' clause, so an agent can distinguish them without opening schemas.

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

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

Explicit 'Use when' (precise coordinates, current + forecast facts) and 'Do not use when' (place name only, ranked sites, night targets), plus named follow-ups get_weather_by_name and plan_stargazing_session. Routing is unambiguous.

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

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

With no annotations, the description carries the full burden and does most of it: it discloses required inputs, the shape of the response (data.grid points with brightness, Bortle class, SQM, bounds, zoom), and that zoom controls granularity. It does not mention rate limits, cost, or caching behavior for what is presumably a remote data fetch, which keeps it short of 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?

Front-loaded with the core action, followed by tightly labeled Use/Do not use/Requires/Returns/Follow-up sections that are easy to scan. The only waste is the redundant restatement of the return value later in the description ('Returns a grid of light pollution data points...'), which repeats the earlier 'Returns' line.

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 5-parameter read tool with an output schema, the definition covers purpose, preconditions, response shape, granularity control, and follow-up routing. An agent has everything needed to decide to call it and to invoke it correctly without further inference.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does: it identifies south/west/north/east as bounding-box coordinates and explains zoom as grid resolution where higher means more detail (the default is already visible in the schema). It does not specify accepted coordinate ranges or zoom bounds, so a small gap remains.

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 ('Get light pollution data') and immediately narrows scope to a 'bounding-box grid of light pollution measurements'. It also explicitly names siblings it is not (ranked places, complete observing decision), so an agent can separate it from analysis_area and plan_stargazing_session without opening schemas.

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

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

Provides explicit 'Use when' and 'Do not use when' conditions, plus a 'Follow-up' line routing to analysis_area, submit_area_analysis, and plan_stargazing_session for the cases this tool does not cover. This is exactly the when/when-not/alternatives structure that earns top marks.

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

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

No annotations are provided, so the description carries the full burden, and it does disclose the key semantic caveat: above-horizon visibility does not imply dark-sky or telescope conditions, plus the required inputs. It stops short of stating whether results are cached or what _meta contains, which is minor for a pure computation.

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 purpose followed by clearly labeled Use when / Do not use when / Requires / Follow-up / Args / Returns sections makes it skimmable, and nearly every line earns its place. The Returns block partially repeats what the output schema already declares, a 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?

Given four required parameters, zero annotation coverage, and an output schema that exists, the description supplies everything an agent needs: preconditions (coordinates, time, timezone), the visibility semantics, sibling routing, and a brief return shape.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: all four parameters are documented with units (degrees for lon/lat), an explicit time string format "YYYY-MM-DD HH:MM:SS", and 'IANA timezone string' for time_zone. Only lat/lon valid ranges are 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 and resource ('Get a list of solar system planets') with a clear scope qualifier ('currently visible, above horizon'), and the usage/exclusion lines separate it from siblings like get_celestial_rise_set and get_best_stargazing_plan.

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

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

Explicit 'Use when' and 'Do not use when' clauses name the exact conditions that select or exclude this tool, and the Follow-up line routes the agent to the correct siblings (get_celestial_pos, get_celestial_rise_set, plan_stargazing_session) with the condition for each.

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?

Goes well past the annotations (readOnly/idempotent/openWorld) by disclosing that this is a synchronous call that can exceed a client deadline and that a timeout does not imply a background task exists. It also explains degradation behavior (missing weather excludes a candidate, decision=null when none qualify, unranked_planning_reference retention) and warns the agent to inspect evidence, uncertainties and missing_inputs even on success.

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, use-when/when-not, requirements and return shape in that order, which is the right structure for a complex planning entry point. It is long and carries some redundancy — civil vs astronomical darkness is asserted twice ('Civil-dark windows are not astronomical darkness' and later 'Civil darkness means Sun below -6 degrees, not astronomical darkness at -18 degrees') — so it is dense rather than tight.

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

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

Even with an output schema present, the description adds the interpretation layer an agent actually needs: recommendation_score is relative not probabilistic, _meta.status=success is separate from decision=null, null observation_window is not an all-night opening, and the named high-uncertainty warnings plus long_range_forecast recheck. It also closes the equipment loop by pointing to decision.targets to avoid a second 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?

The headline schema-coverage metric is 0% (only a $ref at the top level), so the description carries real weight — and it does: it states which fields are required, that timezone/nights/goal/equipment have defaults, that a radius becomes an approximate search box rather than a circular filter, and that quietness/popularity adjustment requires the corresponding flags. It also adds an operational rule the schema cannot express: pass request as a JSON object, not a JSON string, and inspect resolved_location before calling a candidate the exact site.

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 with scope: 'Preferred end-to-end planning entry point for choosing when, where, and what to observe across one to seven nights.' The word 'preferred' implicitly claims primacy over near-neighbors like get_best_stargazing_plan and get_multiday_stargazing_plan, but those overlapping planners are never named, so the agent still has to guess when the others win.

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

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

Explicit 'Use when:' (need a complete observing decision or comparisons of places and nights) and 'Do not use when:' (raw weather, celestial facts, task status) sections, plus a dedicated Follow-up block routing to get_shooting_plan and get_weather_by_position. When and when-not are both spelled out rather than inferred.

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=false, destructive=false, openWorld=true, idempotent=false; the description adds genuinely non-obvious behavior — active duplicate queries share a task and completed retries may hit cached data — which explains the non-idempotent hint. It stops short of stating any authorization, quota, or cost implications of the submission.

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?

Labeled sections (Use when / Do not use when / Requires / Returns / Follow-up) put the decision criteria first and keep every line functional. The final 'plan_stargazing_session for decisions' phrase is compressed to the point of being slightly cryptic, but no sentence is filler.

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

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

Covers the async lifecycle, dedupe/caching semantics, and required inputs, and an output schema exists so return-shape detail is not needed. The only omission is an explicit statement of how this differs from 'analysis_area', which an agent choosing between the two would want.

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?

Top-level schema coverage is effectively nil (one 'request' property with no description), but the nested AreaAnalysisRequest and GeoBounds fields are individually documented. The description only restates that bounds is required and repeats the 1-100 max_locations bound already enforced by the schema, adding little 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?

Names a specific verb and resource ('Submit bounded background place analysis') and states the return ('task identifier'), so the async submit role is unmistakable. It does not explicitly contrast with the sibling 'analysis_area' (the presumable synchronous variant), which is the one remaining disambiguation gap.

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

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

Provides explicit 'Use when' and 'Do not use when' clauses with concrete conditions (long-running place search vs. polling an existing task vs. needing a final decision). The Follow-up line routes the agent to get_area_analysis_task, get_area_analysis_result, cancel_area_analysis_task, and plan_stargazing_session by lifecycle stage.

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