EasyTerritory MCP

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

Adds substantial context beyond the sparse schema descriptions: conflict_policy semantics, that grouping values are labels not balance metrics, the CLARIFICATION_REQUIRED failure mode for visit-frequency, and the map_session_id input path. Annotations already flag destructive/not-idempotent, so the bar is lower, but return semantics (task, tal_id, ts_handle) are also disclosed here.

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?

Dense and information-rich but reads as a run-on of clauses rather than front-loaded prose; the parenthetical example is helpful but the sentence structure is cramped. Every clause earns its place, yet ordering could better lead with the core purpose before the caveats.

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 prerequisites, the key branching parameters, the clarification failure mode, and output shape despite an output schema existing. For a 16-param destructive tool it is nearly complete, though idempotency and expected_revision usage are left unaddressed.

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

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

Schema description coverage is only 13%, so the description must carry the burden and does: it explains conflict_policy, part_scope defaults and part_filter syntax, output_mode implications, visit_frequency_field vs ignore_visit_frequency, and the map_session_id behavior. This compensates well for the near-empty schema.

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

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

States a specific verb and resource (builds territories following an account column) and grounds it with concrete examples (rep name, territory code). It is clearly differentiated from siblings like auto_build, direct_build, seed_build, and create_territory_from_parts.

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 prerequisites (needs ingested point_layer, grouping_field, part_layer, tal_label) and enumerates part_scope alternatives (bbox_intersect vs explicit part_filter). It stops short of naming which sibling to choose instead, so no exclusion routing.

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=false, destructiveHint=false, and idempotentHint=false, so the description needn't repeat safety basics. It adds valuable context by disclosing the side effect of analysis_panel filling the map dock, the task-based return, and the workload omission behavior with workload_omitted.ask_user, all of which help an agent anticipate runtime behavior.

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

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

The purpose is front-loaded, which is good, but the rest is a dense, run-on paragraph mixing input options, metric rules, workload dependencies, panel behavior, and output notes. Some sentences are overly packed, and structuring the details would improve readability without losing 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?

For a tool with 14 parameters, 0% schema descriptions, and an output schema, the description covers the main behavior, input sources, workload handling, panel side effect, and task return. It still omits explanations for several parameters (scope, max_depth, part_layer, compare_tals, visit_frequency_field), leaving gaps that an agent might need to fill by trial or 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 carry parameter meaning. It successfully explains several key parameters (map_session_id, ts_handle, ts, job_id, metrics, tal_ids, dwell_time, analysis_panel, hypothetical_moves), but it leaves scope, max_depth, part_layer, compare_tals, and visit_frequency_field undocumented, so the coverage is partial.

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

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

States a specific verb ('Computes') and resource ('territory statistics for one or more alignments'), and enumerates the core outputs (account counts, metric totals, workload hours, balance scores, cross-TAL comparison). This distinguishes it from sibling analysis tools like analyze_routes and analyze_network_coverage.

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?

Describes input options (map_session_id, ts_handle, ts, job_id) and some conditional behavior (e.g., metrics omission, workload dependency), which implies when the tool is applicable. However, it never explicitly contrasts with alternatives such as territory_rebalance or analyze_network_coverage, and there are no clear when-not-to-use statements.

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 only flag it as a non-idempotent, destructive write. The description adds rich context beyond that: it discloses the straight-line model with 'no provider calls', that it writes new layers but 'never the source', the exact output layers and fields created, the CLARIFICATION_REQUIRED behavior, and that it returns a task whose result carries coverage_pct/gap counts. This is genuinely additive.

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?

Purpose is front-loaded and nearly every clause carries information (coverage rules, side effects, outputs). It is dense and somewhat run-on with stacked parentheticals, which slightly hurts readability, but for a tool this complex little 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?

Given 16 parameters, an output schema, and destructive write semantics, the description covers the essential workflow: required inputs, the three coverage modes, fallback clarification, created layers, and result shape. It omits meaning for several optional parameters (ts, map_session_id, priority_weights, saturation_threshold), which a complex tool arguably needs.

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 16 parameters, so the description must compensate. It does explain the semantic core (coverage rule variants, trade with '*' wildcard, gap_territory adding gap ZIPs as one territory), but leaves roughly ten parameters (ts, ts_handle, tier_field, trade_field, demand_metric, capacity_field, map_session_id, priority_weights, contractor_filter, service_zip_field, saturation_threshold) undocumented. Partial compensation, not full.

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

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

The description gives a specific verb+resource: 'Finds coverage gaps in a contractor... network: counts the contractors that reach each demand point.' It also names the sibling it is not ('dividing work is auto_build'), so an agent can distinguish it from auto_build 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?

It explicitly states the three coverage modes and when each applies (drive_time with max_minutes, drive_time with isochrone_tal, zip_list), the single-trade constraint ('*' for all), and the fallback behavior ('Missing layers, coverage, or trade return CLARIFICATION_REQUIRED'). It also routes the assignment use case to auto_build.

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 read-only, idempotent, non-destructive, closed-world behavior, yet the description adds substantial context: it is synchronous, unresolved dwell returns CLARIFICATION_REQUIRED (needs_dwell), circuit stop_count double-counts the return stop's dwell, and it returns facts only with no capacity/ranking/overload flags.

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 return payload and densely packed with decision-relevant facts; each sentence (sync, dwell resolution, circuit caveat, scope boundaries) earns its place. It is on the longer side but not padded.

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

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

An output schema exists, so return-value detail is supplementary rather than required, and the description still supplies the prerequisite inputs, failure mode, and scope boundaries. An agent has everything needed 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?

Top-level schema coverage is 0%, so the description carries the load: it explains that map_session_id or ts_handle is required, and that dwell comes from dwell_time or the route's recorded dwell. This meaningfully compensates for the sparse top-level schema, though it does not detail route_ids itself.

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

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

States a specific verb and resource (returns total hours for each route) and enumerates the exact output fields (drive hours, dwell hours, route_workload_hours, coordinates, centroid, bbox). It clearly distinguishes itself from calculate_route (which draws the routes) and analyze (which handles territory statistics).

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?

Names the producing sibling (calculate_route) and routes territory/cluster workload questions to analyze, plus states the requirement of map_session_id or ts_handle. It stops short of an explicit 'use this when / do not use this when' formulation, but the context is clear enough to select correctly.

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 beyond the annotations (destructiveHint/openWorldHint/idempotentHint) by disclosing that it returns a task, that national builds take minutes, that estimated_remaining_ms is capped and not a forecast, what the result carries (tal_id, ts_handle, phase_timings_ms), and that analyze provides statistics. This is real behavioral context not present in 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?

Purpose is front-loaded, but the body is a dense, comma-spliced paragraph stacking many parenthetical clauses, which makes it harder to scan for a single decision. The information is largely warranted for a 17-param tool, but the structure could be tightened.

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, non-idempotent, destructive build tool with 17 parameters and an output schema, the description covers the decision-critical inputs and the async/task nature well, so an agent could invoke it and know how to respond to CLARIFICATION_REQUIRED. Remaining gaps are peripheral params rather than core flow.

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

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

With schema coverage at only 12%, the description carries the load and does so for the key knobs: build_mode variants, objective bias semantics ('biases sum to 100'), dwell_time as column-or-scalar, part_scope defaults, and the visit_frequency_field/ignore_visit_frequency requirement. Still, several parameters (tal_label, ts, ts_handle, part_ids, expected_revision) are left unexplained in both schema and description.

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 precise verb+resource: 'Partitions ingested account points into balanced sales territories ... as a new alignment (TAL)', with the balancing dimensions spelled out. It does not, however, distinguish itself from sibling builders like direct_build, seed_build, or account_build, so an agent cannot fully tell why it should pick auto_build over them from the text alone.

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 usage context: which choices must be supplied (build_mode, objective, dwell_time), that missing choices trigger CLARIFICATION_REQUIRED with ask_user, that map_session_id makes the open map the input, and how part_scope/part_filter behave. It omits any explicit 'use this instead of X' routing against the other build 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 declare a non-read-only, non-idempotent, open-world operation, and the description adds materially: recalculating an existing route_id replaces the prior route (e.g. to drop a stop), provider dependency (TomTom/Azure Maps), specific failure codes ROUTING_NOT_CONFIGURED and PROVIDER_QUOTA_EXCEEDED, and that it returns a task. That is behavioral context well 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?

Purpose and return values are front-loaded and nearly every sentence carries a distinct fact (ordering semantics, group bands, error codes). It is dense and paragraph-form rather than scannable, and a few clauses could be tightened, but there is little pure filler.

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

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

For a 12-parameter, nested-schema, async tool with an output schema, the description covers the operation's mechanics, side effects, provider errors, and sibling relationships well. Gaps remain around travel_mode/depart_at semantics and the start/end object shapes, but the output schema means return values need not be restated.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does for route_type (circuit/tour/open_tour), stop_sets ordering, route_id create-vs-replace, dwell_time, and map_session_id. However travel_mode, depart_at, ts_handle, route_label, include_geometry, and start/end shapes are left unexplained, so roughly half the 12 parameters remain undocumented in both places.

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 precise verb and resource ('Sequences and drives a set of stops') and enumerates the concrete outputs (order, road distance, drive time, per-leg timings, geometry, numbered stops on the map). It also explicitly separates itself from siblings: 'Creates no territory and changes no assignment,' distinguishing it from create_territory/realign, and links dwell_time to analyze_routes.

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 clear context on when to call it (sequencing a technician's day) and what it does not do versus neighboring tools, plus the create-vs-recalculate distinction for route_id. It stops short of an explicit 'use X instead of Y when...' rule, so it is strong context without full alternative routing.

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 names the write side effect (group_field written on every point, default group_id), the destructive consequence of 'replacing any prior color classification' while preserving size/shape channels, the clarification-failure behavior, the 10,000-point ceiling, and the task/return structure. This is exactly the extra context destructiveHint=true alone cannot convey.

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, then side effects, then requirements, then the seed variation and return shape. Dense but nearly every clause carries distinct information; the single long paragraph is heavy to parse but not padded.

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 15-param mutation tool with no annotation-level detail beyond flags and a confirmed output schema, the description covers effect, prerequisites, limits and errors well enough to call it safely. The remaining gap is the several unmentioned parameters, which slightly undercuts completeness.

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

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

With 15 parameters and near-zero top-level schema description coverage, the description carries the burden and covers the important ones well: build_mode values, objective, dwell_time, point_filter syntax with an example, group_field default, seed_point_layer semantics. However ts, ts_handle, metric_fields, map_session_id, expected_revision, group_label_prefix and visit_frequency_field are entirely unexplained, leaving a large undocumented remainder.

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 ('Groups the points of one ingested layer into balanced clusters') and immediately differentiates itself from alternatives by scope: 'with no ZIP or part layer and no territory alignment'. An agent can distinguish it from auto_build, seed_build, direct_build and the part-based tools 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 clear operating context (ingested point layer only, must supply build_mode/objective/dwell_time 'as in auto_build', missing returns CLARIFICATION_REQUIRED) and scopes the optional seed path. It never explicitly says when to prefer this over auto_build or seed_build, so the routing guidance is inferred rather than stated.

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 destructiveHint=true and idempotentHint=false, and the description adds real behavioral context beyond them: the live map jumps to the new center/zoom, the server computes classification breaks and returns per-class counts, only one classification per channel per layer is allowed, clear:true removes one, and classification without point_layer is a project-level setting that does not color points. It does not explain the merge_strategy semantic or what the destructive refresh actually overwrites, which keeps it from a 5.

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

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

The purpose is front-loaded, but the body is a single dense run-on with many parenthetical clauses and inline enumerations that make it hard to scan for a specific parameter. Every element is arguably informative, but the lack of any structuring (bullets, grouping of related settings) costs readability on a 15-parameter tool.

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

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

An output schema exists, so return values need not be spelled out, and the description does valuable work covering layer and symbology semantics. However, for a destructive, non-idempotent mutation it is silent on merge_strategy, expected_revision, and expected_content_hash, which look like concurrency/conflict-control parameters an agent must understand to call this safely.

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% with 15 parameters, so the description carries the full burden, and it defines most of them in prose: project_name, loaded_part_layers (including the [] special case), active_part_layer, active_tal_id, center, zoom, point_layer_classifications sub-fields (method enum values, class_count range, channel, colors/sizes/shapes), classification, and the map_session_id/ts_handle/ts inputs. It leaves presentation, merge_strategy, expected_revision, and expected_content_hash entirely unexplained, which is a notable gap for a destructive write.

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 ("Updates map settings on the Territory Solution and refreshes the live map") and then enumerates exactly which settings are in scope, from heading and part layers to point symbology. It is clearly a map-configuration tool, though it never names the nearest sibling (set_map_state) to draw a boundary, so sibling differentiation relies on the reader knowing the other tools.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named despite siblings like set_map_state, ensure_map_viewer, and get_map_visualization occupying similar space. The closing "Input: map_session_id (the live map), ts_handle, or ts" is input-selection help, not usage routing, so an agent gets no rule for choosing this tool over a neighbor.

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?

Against annotations that only flag destructive/non-idempotent/non-readonly, the description adds substantial context: the live-map repaint side effect, the returned ts_handle, precedence when both handles are passed, that dwell is not inherited from an earlier auto_build, and the downstream analyze consequence (workload_omitted.ask_user). It even states the return is a task, which matters for an agent's follow-up.

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 layers the branching and downstream effects. It is dense and parenthetical-heavy, but nearly every clause carries operational information rather than restating the name.

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

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

An output schema exists, so return-value explanation is not strictly needed, and the description still notes created_territory.territory_id, leaf_territories, and selection_summary. However, for an 11-parameter destructive operation several parameters (part_layer, repair_policy, conflict_policy, territory_path) remain undocumented, leaving meaningful gaps.

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

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

Schema description coverage is 0% across 11 parameters, so the description must compensate and only partly does: it explains part_ids, tal_id, ts_handle, map_session_id, territory_name, and dwell_time semantics. Required parameter part_layer and the repair_policy/conflict_policy/territory_path parameters go entirely unexplained in both places.

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

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

The description opens with a specific verb+resource+scope: 'Creates one leaf territory from a list of part_ids', which tells an agent exactly what is produced and from what input. It stops short of naming how it differs from sibling builders like auto_build, direct_build, or seed_build, which also create territories.

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 real routing rule for the two creation paths (map_session_id updates and repaints the live map; otherwise ts_handle, with map_session_id winning when both are passed), but that is parameter selection, not when to choose this tool over the other build tools. No explicit when-not or alternative-sibling guidance is 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 destructiveHint=true, readOnlyHint=false, idempotentHint=false, so the safety profile is covered; the description adds real value on top: it says the call is synchronous, that account points go with the layer, that a derived visit layer is kept and reported, and that ambiguous labels yield AMBIGUOUS_POINT_LAYER with matching_point_layers. Minor tension with idempotentHint=false, since a repeat delete returns ok rather than an error, but no hard contradiction.

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

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

Front-loaded with the action, then scope, then error/edge behavior; every sentence carries distinct information with no filler. It is dense and packs several facts per sentence, which slightly taxes readability but does not waste 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?

An output schema exists, so return values need not be explained; the description nonetheless covers the edge cases an agent needs (absent layer, ambiguous label, what survives the delete, prerequisite relationship with ingest_accounts). Nothing material for a 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 0%, so the description carries the full burden and does: point_layer is 'the layer id or its exact unique label' (explaining the ambiguity error path), and map_session_id vs ts_handle are presented as alternative context selectors. All three parameters gain meaning not present in 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?

Opens with a specific verb+resource ('Point-layer delete: removes one point layer and its account points') and states the scope precisely ('from the Territory Solution and the open map'). It also scopes what is NOT touched (territories, part overlays, other point layers), making it easy to separate from delete_territory or ingest_accounts.

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

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

Explicitly names a sibling and the condition that selects this tool: 'ingest_accounts does not replace an existing layer; delete it here first.' It also gives the failure/retry contract (already_absent=true on re-delete) and the alternate selector set (map_session_id or ts_handle).

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 destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: synchronous execution, the already_absent=true success case, and the AMBIGUOUS_ROUTE error with matching_route_ids. Slight tension with idempotentHint=false (re-deleting a gone route returns ok), but not a direct contradiction.

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

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

Front-loads the core action and scope, then layers input requirements, edge cases, and the sibling alternative. Dense but every clause carries information; slightly long but not padded.

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

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

An output schema exists so return values need not be explained, yet the description proactively covers error and no-op outcomes. Combined with the input guidance and clear alternative routing, an agent has everything needed to call this 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 0%, so the description must carry the load and largely does: it clarifies that route_id accepts a route id or an exact unique label, and that map_session_id and ts_handle are interchangeable session handles. It omits format specifics for the session identifiers, keeping it short of a 5.

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

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

States a specific verb and resource: 'removes one whole route from the Territory Solution and the open map.' It also explicitly contrasts with the sibling calculate_route for single-stop removal, so the agent can distinguish 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?

Gives explicit input requirements ('needs route_id or the route's exact unique label, plus map_session_id or ts_handle') and routes the agent to the alternative path for removing one stop via calculate_route. When-to-use and when-not are both covered.

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

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

Goes well beyond the annotations by disclosing side effects (points, part-layer overlays and routes survive; the map falls back to a remaining alignment or points only), the synchronous nature of the call, the already_absent=true no-op result, and the AMBIGUOUS_TAL error path. The already_absent behavior is arguably idempotent while annotations claim idempotentHint=false, but this reads as a partial-no-op nuance rather than a contradiction.

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

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

Front-loads the destructive action and scope in the first sentence, then layers constraints and fallbacks efficiently. Dense but every sentence carries distinct information; borderline on length for a single-call tool.

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

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

Output schema already covers return values, yet the description still surfaces the notable result states (already_absent, AMBIGUOUS_TAL) and the post-delete map behavior. Nothing an agent needs to invoke this destructively and safely 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?

With 0% schema description coverage the description must carry the parameter burden, and it does explain that tal_id accepts an id or an exact unique label and that map_session_id/ts_handle are alternative context handles. It never clarifies the relationship or precedence between ts_handle and map_session_id, leaving that pair ambiguous.

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

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

States a specific verb (deletes) and a precisely scoped resource (one whole territory alignment, explicitly glossed as 'the territory layer', 'all territories'), and distinguishes it from the nearest sibling by naming delete_territory for the single-territory case.

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 the required inputs (tal_id or exact unique label, plus map_session_id or ts_handle) and explicitly routes the neighbouring case to delete_territory, so an agent can choose between the two without opening either schema.

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 destructiveHint=true and idempotentHint=false. The description adds real value beyond that: what happens to the leaf's parts (they become unassigned), the already_absent=true ok-return for an already-deleted territory, that a task is returned, and that the open map repaints.

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

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

Front-loads the action, then requirements, edge-case behavior, and sibling routing in four dense sentences with no filler. The information is packed but 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 destructive mutation with annotations covering the safety profile and an output schema covering return values, the description supplies prerequisites, edge-case semantics, and alternatives. The only gap is the unaddressed part_layer and expected_revision 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 only 13%, so the description must compensate; it explains that territory_id accepts the leaf id or its exact unique display name, and clarifies that the Territory Solution may come from map_session_id, ts_handle, or ts. It leaves part_layer and expected_revision undocumented, so compensation is partial rather than complete.

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 ("Deletes one leaf territory from an alignment") with clear scope. The Related sentence explicitly contrasts it with territory_merge and delete_tal, letting an agent distinguish it from siblings without opening a schema.

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

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

Names concrete alternatives with the condition that selects them: delete_tal "removes a whole alignment in one call" vs. this tool's single-leaf scope, and territory_merge for reassigning a departing rep's territory. Clear context, though it stops short of an explicit when-not-to-use rule.

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 destructive=true, idempotent=false, readOnly=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it creates a new TAL alignment, duplicate handling defaults to keep_first, auto-maps common column names, and it returns a task whose result carries tal_id and ts_handle while painting the open map. It could say more about how destructive the operation is to existing TALs, hence 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?

Dense and front-loaded: the core action and the input formats lead, and the sibling routing comes last. It remains readable, though the run-on listing of alternative tools is packed tightly.

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 spelled out, yet the description restates the task/result contract usefully. However, for a 12-parameter destructive tool with 8% schema coverage, several parameters go unexplained in both description and schema, leaving real gaps.

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

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

Schema coverage is only 8% and there are 12 parameters, so the description must carry the load. It clarifies assignments vs assignments_handle, duplicate_part_policy (keep_first), territory_path, and implies part_layer/tal_label usage, but leaves ts, tal_id, ts_handle, map_session_id, expected_revision, and missing_part_policy unexplained. Partial compensation earns a mid score.

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 ('Builds territories from known part-to-territory assignments') and immediately differentiates itself from siblings by naming the exact input shape (ZIP-to-territory sheet, territory_path hierarchy) and how it produces a new alignment (TAL). An agent can distinguish it from auto_build, account_build, and create_territory_from_parts 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?

Explicitly routes the agent: 'Location points load with ingest_accounts; balanced partitions come from auto_build; grouping by a column is account_build', and tells the agent to source assignments via request_assignment_upload. This is when-to-use/when-to-use-alternative guidance of the highest quality.

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. 'Read-only keyword routing; no compute' plus the 'null when the request is ambiguous' note add real behavioral value, but the long recital of return fields duplicates the existing output schema rather than disclosing new 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?

Core purpose and the read-only/no-compute constraint are correctly front-loaded. However, one very long sentence mixes a return-field inventory (redundant with the output schema) into what should be a routing catalog, and the topic enumeration could be trimmed.

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 router tool with an output schema, the description need not detail return values, and it does convey which capabilities it can route to. The gap is the undocumented `context` parameter, which matters more given 0% schema coverage.

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

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

Schema description coverage is 0%, so the description carries the full burden. It clarifies user_request as a 'free-text territory request' with examples of expected phrasing, but the optional `context` object parameter is never mentioned anywhere, leaving half the parameters undocumented.

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

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

States a specific verb and resource: it maps a free-text territory request onto a workflow, and it names the mechanism ('Read-only keyword routing; no compute'). The enumeration of covered domains (build, edit, analyze, geocoding, schedules, coverage) makes it unmistakable which sibling capabilities it fronts.

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 the routing role clearly enough that an agent knows to call it first on an ambiguous free-text request, and it names the categories it can route to. It stops short of explicitly naming alternatives (workflow_advisor, get_guidance) or stating when a direct tool call is preferable over 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?

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the max 30 s per call, the requested_wait_seconds/max_wait_seconds reporting, the VIEWER_NOT_CONNECTED return while closed, and that it behaves identically for the in-chat map and map_url tab.

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 only four sentences, each adding value (timeout, return signal, repeatability, dual-target behavior). Slightly dense with parenthetical detail, but no filler.

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

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

With an output schema present, return values need not be re-explained, and the description still supplies the key polling-loop semantics and the connect/disconnect signal. The only meaningful gap is the unexplained poll_interval_ms parameter.

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

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

Schema coverage is 0%, so the description carries the burden. It explains wait_seconds (max 30 s per call) and identifies map_session_id's origin, which is substantial, but poll_interval_ms is never mentioned and its units/meaning are left entirely undocumented.

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

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

States a specific verb+resource: reporting whether the person has the map open for a given map_session_id, and explicitly ties the session id source to get_map_visualization. An agent can distinguish this 'wait for viewer connection' tool from sibling map tools like get_map_visualization and set_map_state.

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 clear usage context: repeat the same call while the person opens the map, and that results paint live once connected. It references get_map_visualization as the session-id source. However, it does not explicitly exclude or contrast alternatives (e.g., set_map_state, configure_map), so routing guidance is strong but not fully disambiguating.

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 closed-world, so the safety burden is offloaded. The description adds a genuinely non-obvious behavioral caveat: it silently returns no edges unless the pack ships a _graph.yaml, which prevents an agent from misreading an empty result as 'nothing related exists'.

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

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

Two tight sentences with zero filler: the core behavior and the example come first, and the critical caveat follows. Every clause earns its place, and no sentence merely restates 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?

An output schema exists, so return values need no explanation, and the _graph.yaml caveat covers the main surprise. However, the description leaves edge_kinds undefined and keeps 'related guidance' vague, which is a real gap for a graph-query tool at this parameter-coverage level.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains file_path concretely (with a worked example path) and clarifies that depth caps the number of hops, but edge_kinds is never mentioned, leaving a third of the parameters undocumented in both schema and description.

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 ('Traverses') and resource ('the EMEP knowledge graph') and clarifies the starting point (a topic file) and endpoint (related guidance). It is distinguishable from ep_search/get_guidance in mechanism, though it never names those siblings directly, so the differentiation is inferential rather than stated.

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 the scenario (go from a topic file to related guidance) but gives no explicit when-to-use versus the plausible alternatives ep_search, ep_list_topics, or get_guidance. The only constraint offered is a failure precondition (_graph.yaml), not usage routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the grouping semantics (topics grouped by type) which is useful context, but does not mention output shape, whether the list is complete or paginated, or the values the type filter accepts.

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

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

One concise sentence that front-loads the action and enumerated categories, followed by a short clause on the optional filter. No 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?

Output schema exists, so return values needn't be described, and annotations cover the safety profile. However, for a list tool whose only parameter is undocumented in the schema, the description should more clearly specify the filter's accepted values and default. Adequate but with gaps.

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

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

Schema description coverage is 0% for the single 'type' parameter, so the description must compensate. It names the five valid type values (concept, workflow, interface, troubleshooting, decision) in the grouping parenthetical, which is genuinely useful, but does not explicitly tie them to the filter parameter or state the default behavior.

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 (EMEP topics), and adds useful detail that topics are grouped by type with the enumerated categories. It doesn't name a sibling to distinguish from (e.g. ep_search, ep_graph_traverse), but the purpose is clear.

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

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

No when-to-use guidance and no alternatives named. Given siblings like ep_search and ep_graph_traverse exist in the same 'ep_' family, the description should say when listing is preferable to searching or traversing, but it provides none.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and non-open-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: ranked markdown chunks with source files, the requires_expanded flag for atoms pulled in via `requires`, and graceful degradation to ezt://guidance/... resources when retrieval is unavailable.

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

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

Front-loaded with purpose, then return behavior, then fallback, then examples — a sensible ordering with little waste. Slightly dense in the middle clause about requires_expanded, but every sentence carries information an agent needs.

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

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

An output schema exists, so return-value explanation is not required, and annotations cover safety. The description fills the remaining gaps (fallback path, result shape, example intents), leaving only parameter documentation unaddressed for a 4-parameter 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 0% for four parameters, and the description says nothing about what `tags`, `type`, or `max_results` mean or accept (no enum or format hints, despite `type` clearly being a filter). The query examples only indirectly illustrate the `query` parameter; the filtering and pagination parameters are entirely undocumented in both places.

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 ('semantic search') and a specific resource ('EZT MCP Expert Pack (EMEP)') and enumerates the content types it covers (workflow guidance, concepts, interfaces, common mistakes). This distinguishes it from siblings like ep_list_topics (enumeration) and ep_graph_traverse (graph traversal) without needing to name them.

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 three example queries ('build balanced territories from accounts', 'viewer not connected before compute', 'auto_build vs account_build') effectively demonstrate when this tool is the right choice, and the degradation note tells the agent what happens if retrieval fails. However, it never explicitly states when NOT to use it or which sibling to prefer for structured topic browsing.

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 declare the safety profile (not readOnly, not destructive, not idempotent, not open-world), and the description adds substantial context beyond that: the operation returns a task whose result is geojson_artifact plus a download_url, the download is a GET requiring the API key, and the payload is gzip unless zip=false rather than an inline body. These async-task and auth/gzip details are exactly the behavioral traits an agent needs and are not derivable from 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?

The purpose is front-loaded in the first clause, and most sentences carry distinct information (contents, filters, inputs, return/download mechanics). It is a dense run-on block that could be split for readability, but there is little waste.

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

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

For a nine-parameter export tool, the description covers inputs, filtering flags, the output artifact shape, and the download mechanism. An output schema already exists, yet the description still usefully explains the task/download return path, leaving no material gap for an agent to call it correctly.

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

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

With 0% schema description coverage, the description must carry all nine parameters, and it largely does: zip controls gzip, tal_ids/point_layers/route_layers narrow the output, include_points/include_routes drop a family, and map_session_id / ts_handle / a completed build job_id are the accepted inputs. The only shortfall is that it groups the three narrowing ids under a generic 'narrow it' without saying which filters territories versus points versus routes.

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 (exports the territory solution as one GeoJSON file) and enumerates exactly what is included: territory polygons with part_ids, points, and routes with numbered stops carrying displayed style. It also names the companion tool import_geojson, so an agent can distinguish this export from its sibling 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 clear context for when to reach for it (to share, archive, or open in EasyTerritory Designer) and notes that import_geojson reopens the file, establishing the export/import pairing. It stops short of explicit when-not-to-use or alternative-routing guidance, but no competing export sibling exists, so the context is adequate.

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 destructive/not-readonly/not-idempotent, so the safety bar is partly covered. The description adds valuable behavior beyond that: the return payload includes an extract plus branch_metadata, the downstream reintegration dependency, and the exclude_locked default semantics.

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 front-load the operation, then the workflow reason, then the return contract and default. No filler and every clause carries information.

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

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

Purpose, workflow linkage, and return essentials are present, and an output schema exists so return details needn't be spelled out. However, for a 10-parameter tool the bulk of parameters (identity and concurrency guards like expected_revision/expected_content_hash) remain unaddressed.

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 10 parameters. The description only illuminates the either/or branch selector (branch_rollup_territory_id or branch_territory_path) and exclude_locked's default; tal_id, ts, ts_handle, delegate_ref, map_session_id, expected_revision, and expected_content_hash are left entirely unexplained.

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 'Extracts' with a precise resource ('one regional branch of a hierarchical alignment into its own Territory Solution') and names the branch selector keys. It is clearly distinguishable from sibling reintegrate_branch, which it explicitly references.

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?

States the rationale ('so a delegate can edit just that region') and the workflow linkage ('branch_metadata, which reintegrate_branch needs later'), giving strong context for when to extract. It stops short of explicit when-not-to-use guidance or naming an alternative for non-delegated edits.

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 destructive=true, non-idempotent, open-world, so the safety profile is covered. The description adds genuine behavioral context beyond them: CSV is parsed/staged/ingested onto the open map, target_hours/workload_target trigger a fixed-workload auto_build, and missing inputs return CLARIFICATION_REQUIRED with questions. It doesn't contradict the destructive annotation, and the added failure-mode disclosure is valuable.

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 purpose and orchestration role, then details on CSV handling and clarification behavior. Dense but mostly earns its place; a few parenthetical asides add slight noise without much cost.

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, and annotations cover safety. However, for a destructive open-world orchestrator with 8 params, the description leaves the space of 'matching workflows', the request format, and the args/state_facts params unexplained, so an agent still lacks enough to invoke it confidently in edge cases.

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

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

Schema description coverage is 0% across 8 params, so the description carries the full burden. It adds meaning for request, csv_file, accounts_handle, assignments_handle, map_session_id, and ts_handle, but leaves args and state_facts undocumented and gives no format or handle semantics. It also references target_hours/workload_target which are not top-level schema params, leaving some ambiguity.

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 role (plain-language orchestrator) with a clear verb+resource: it takes a goal and runs the matching workflow in one call. It also explicitly distinguishes itself from siblings by noting 'The granular tools do the same steps individually,' so an agent can tell it apart from auto_build, direct_build, etc. 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?

The description makes the selection context clear: use this to run a workflow in a single call versus the granular tools that do the same steps individually. It does not state explicit exclusions or name which specific sibling to prefer for a given request, so it falls short of a full when/when-not rubric.

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 only mark readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds critical behavior annotations do not: caching is free while billable lookups count against a monthly per-key quota, and the exact quota-exceeded response shape (PROVIDER_QUOTA_EXCEEDED with limit, used, remaining, period_resets_at). This is high-value behavioral context.

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

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

Four dense sentences covering purpose, input shape, quota behavior, and output/routing. Front-loads the core purpose but the quota sentence is long; still, every sentence earns its place with little waste.

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

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

An output schema exists so return-value detail is not required; the description nonetheless names geocoded_rows and its downstream consumer. It covers cost/quota, input column mapping, and the sibling alternative. Completeness is slightly reduced by undocumented semantics of 6 of 8 parameters, though most are self-explanatory from names and defaults.

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 explains accepted address column variants (address/address_line1/street, city, state, postal) and mapping of common CRM headers, and explains accept_suboptimal_geocodes. It still omits the purpose of use_cache, region_hint, country_hint, map_session_id, min_confidence, and force_regeocode, leaving half of the 8 params opaque.

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 (geocodes) plus resource (a list of customer addresses) and the output (coordinates with match confidence). The clause 'without loading them as a point layer' distinguishes it sharply from layer-building siblings like import_geojson or seed_build.

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 names the alternative ingest_accounts twice: it says ingest_accounts also geocodes on its own, and that this tool's output can be loaded by ingest_accounts. It also clarifies when to relax matching (accept_suboptimal_geocodes=true for ZIP-centroid matches). This gives the agent a clear routing decision between the two geocoding paths.

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 (and 'Read-only' merely echoes it). The description adds genuine value the annotations don't: it discloses the payload contents, including quota_remaining broken out for geocoding, routing, and isochrone requests, plus seat plan values and key expiry.

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 but well-ordered sentences: identity and payload first, usage note last. Every clause maps to real returned data, though the parenthetical seat/quota enumeration makes the second sentence slightly heavy.

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

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

With an output schema present the return shape needn't be re-explained, yet the description still names the key result fields, tells the agent when to call it, and repeats the read-only nature. Nothing needed to invoke a zero-parameter, read-only guidance tool is missing.

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

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

The tool takes zero parameters, so there is nothing for the schema to document and the baseline of 4 applies. The description correctly adds no parameter discussion, consistent with an empty arguments object.

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 (Returns) and resource (the EZT MCP operating guide), then enumerates exactly what that covers: cross-tool workflow order, shared rules, result.server_version, and seat/quota details. An agent can tell this is a meta/onboarding tool distinct from task-oriented siblings like workflow_advisor or analyze.

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?

'Useful at the start of a session or for a host that does not show server instructions' gives explicit when-to-use context. It does not, however, name or exclude any alternative sibling (e.g., workflow_advisor), so the routing guidance is context without explicit alternatives.

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, closed-world, so the safety profile is covered. The description adds a genuine behavioral detail: only committed (not in-progress) selections are returned, and selection_task_id is present only for request_part_selection-derived selections. It says nothing about what happens with an invalid/closed session or an empty selection.

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 dense sentences with the core purpose front-loaded and no filler. The third sentence about realign is a useful cross-reference, though it slightly buries the primary contract.

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 explaining return values is optional; the description nevertheless frames the key conditional field and the realign downstream use. For a single-param read tool with full annotations, this is nearly complete, missing only error/empty-selection behavior.

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?

One parameter at 0% schema coverage, so the description must carry meaning; it does imply the id must refer to an open map session, which is real semantic value. However it gives no format, source, or failure behavior for the id, so compensation is only partial.

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

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

Specific verb+resource: it retrieves the most recent committed selection for an open map session, and enumerates the payload (part_layer, part_ids, selection_task_id). It scopes itself with 'selections the person started from the map legend', which helps separate it from the similarly named get_part_selection, but it never names that sibling explicitly.

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 implied rather than stated: the agent learns this applies to map-legend-originated selections on an open session, and that realign consumes these part_ids. There is no explicit when-not-to-use or direct pointer to the alternative get_part_selection for other selection sources.

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

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

The description claims 'Idempotent per user_id: a second call returns the same map,' but the annotations declare idempotentHint=false, a direct conflict on the same property. Despite otherwise rich disclosure (destructive new_project, host-dependent rendering, session handoff), this contradiction of an annotation is flagged.

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

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

Front-loads the action and return values, then layers in sourcing, idempotency, and host behavior. Dense but every clause carries information, though the run-on accumulation of distinct facts slightly hurts scanability.

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 a complex host-dependent tool with 10 params and an output schema (so return values needn't be detailed), the description still names map_url/map_session_id and covers rendering, session reuse, and destructive new_project. Four parameters remain undocumented, leaving a modest 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% (10 undocumented params), so the description must compensate and does so well: it explains ts, ts_handle, job_id, user_id, new_project, and the presentation.view_name enum values (empty | points_only | review | selection). It leaves mode, active_tal_id, expiry_seconds, and interaction_flags unexplained.

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 ('Opens the interactive territory map (Map Component)') and names its outputs (map_url, map_session_id). It differentiates itself from siblings by noting that 'Later map tools take map_session_id' and citing ensure_map_viewer as the status reporter.

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 clear context for the two modes: opening a blank map, or resurfacing the latest state of an existing Territory Solution via ts, ts_handle, or a completed job_id, and explains new_project=true. It stops short of explicit when-not-to-use guidance or a fuller alternative-tool routing.

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. The description usefully adds the lifecycle state machine (awaiting_user_selection/committed/expired/cancelled), the polling cadence hint, and the TAL assigned-vs-unassigned distinction, all of which go beyond the structured safety flags.

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 purpose and dense with useful detail, but the parenthetical nesting and colon-delimited lists make it a single heavy sentence that is denser than ideal. Every clause still carries signal, so no trimming is obviously safe.

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

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

With an output schema present, return values need not be re-explained, and annotations carry the safety profile; the description covers the state machine, polling, and downstream usage. It stops short of distinguishing this tool from the similarly named get_map_selection sibling, which is the remaining ambiguity.

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% and the single parameter has no schema description, but the description compensates by stating where selection_task_id comes from (output of request_part_selection or active_selection_task_id in ezt://map-sessions/{id}/state), which is meaning the bare schema does not provide.

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

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

States a specific verb and resource ('Returns the state of a map selection task') and enumerates the exact status values it can return, so the agent knows precisely what it retrieves. It differentiates from the producing sibling request_part_selection by naming it as the source of the id, and names realign, create_territory_from_parts, and analyze as downstream consumers of a committed result.

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 explains how to obtain selection_task_id (from request_part_selection or active_selection_task_id in session state) and signals polling via recommended_poll_delay_ms while awaiting, plus what to do with committed part_ids. It gives clear context but never explicitly excludes the confusable sibling get_map_selection.

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 destructive/non-idempotent/closed-world, so the safety profile is covered. The description adds real value beyond that: the specific error TERRITORY_POLYGONS_WITHOUT_PART_IDS, the part-assignment fallback via part_layer + overlay_policy=centroid_within, and the return of ts_handle.

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

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

Front-loads the purpose and return values in the first sentence, then layers input forms and behavior. It is dense but nearly every clause carries information; only the Designer project path sentence feels marginally bolted-on.

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 spelled out, and the description still summarizes them. Input options, a key error condition, and the part-assignment workflow are covered, making it sufficiently complete for a 7-parameter import 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 0%, so the description must carry the load, and it names all seven parameters with meaning: geojson object, geojson_text, geojson_gzip (base64), point_layer, tal_label, part_layer, and overlay_policy. Only overlay_policy's full value set and geojson's object shape remain under-specified.

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 (opens/imports) and resource (GeoJSON FeatureCollection) plus the outcome (a Territory Solution with ts_handle and summary). This clearly distinguishes it from the sibling export_geojson (the inverse) and from create_territory_from_parts.

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 clear context for input selection (plain points vs. a server-produced territory file, gzip/zip, and the EasyTerritory Designer project case that must use geojson_gzip). It doesn't explicitly say when to prefer this over create_territory_from_parts or other build tools, so no explicit 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 only flag non-readOnly/open-world; the description adds the real behavioral load: CLARIFICATION_REQUIRED (needs_coordinate_fields), needs_unique_row_id on duplicates, UNDECLARED_FIELD on later use, geocode quota shortfall, and the failed_rows/map_refresh task result. This is far beyond what 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?

Front-loaded with the purpose and inline-vs-handle decision, but the second half is a dense run-on of error codes and field lists that is hard to parse in one read. Efficient per-sentence, but the whole block is heavy and undifferentiated.

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 inputs, error/return behavior (failed_rows, map_refresh, geocode quota shortfall), and the contractor branch, and an output schema exists so return values needn't be re-explained. Slight gaps remain around auth/handle lifecycle (ts_handle, map_session_id, use_cache) which are undocumented anywhere.

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 29 parameters, so the description carries the full burden and does: it names coordinate aliases (latitude/lat, longitude/lon/lng), id_field default row_id, label defaulting to point_layer id, the column-declaration families (metric/workload/display/search/grouping/dwell_time/visit_frequency), and the contractor extras. This is a rare case of a description meaningfully documenting a large param surface.

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

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

Opens with a precise verb+resource ('Account ingest: loads account or location rows ... as point data on a named point layer') and names the sibling it routes from (request_account_upload). It distinguishes itself from geocode_address and the various *_build tools by being the point-data ingestion path.

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?

Tells the agent when to pass inline rows vs accounts_handle, when to use latitude_field/longitude_field, and when layer_role=contractors applies. Missing a plain when-not-this-tool statement naming geocode_address or import_geojson as alternatives for already-geocoded data.

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 annotations already declaring openWorldHint=true, idempotentHint=false and destructiveHint=false, the description still adds substantial context: hard limits (25 origins, 5 bands, 6 hours, 500 km), the one-unit-per-call rule (MIXED_BUDGET_TYPES), overlap semantics, that analyze counts accounts in every containing area, three named error conditions including quota being checked before the call, and that it returns a task. This is well beyond what the annotations convey.

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?

Purpose is front-loaded in the first clause, and each subsequent sentence carries distinct information (shapes, limits, semantics, errors). The error-code and quota detail is dense but earns its place for a provider-backed call; the prose is compact given how much is packed in.

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 'Returns a task' suffices for the return value, and the failure modes, limits, and overlap semantics are covered. The remaining gap is the undocumented half of the parameter set, which is not addressed anywhere.

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 11 parameters, so the description must carry the load. It explains origins, bands, travel_mode (car/truck), and depart_at, but leaves avoid, traffic, route_type, tal_id, tal_label, ts_handle, and map_session_id entirely unexplained in both schema and description. Partial compensation only.

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 ('Draws the area reachable by driving from one or more origins') and names the artifact it produces (a territory in a drive-time alignment). It also disambiguates from nearby siblings like calculate_route and analyze_routes by noting the budget is not route time or territory workload. 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?

Gives explicit conditions and exclusions: realign/split/merge/rebalance return ISOCHRONE_TAL_NOT_EDITABLE, so those tools cannot edit these areas, and it clarifies that a band budget is not territory workload or route time. It never names a positive alternative (e.g., use calculate_route for point-to-point), so it falls short of a 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?

Annotations already declare readOnlyHint and idempotentHint, and the trailing 'Read-only' merely restates them. Beyond that, the description adds genuine value: the exact metadata fields returned, the extra detail fields for single-layer lookups, and the UNKNOWN_PART_LAYER sentinel for bad input, which is useful operational behavior.

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

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

The purpose is front-loaded in the first clause, which is good. But the long enumeration of output fields (part_layer, label, description, country_codes, admin_levels, part_count, id_format, ...) largely duplicates what the output schema already provides and bloats an otherwise single-sentence definition.

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

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

With an output schema present, the description need not explain return values, and it correctly focuses on parameters, the read-only nature, and the unknown-layer sentinel. It is complete enough to invoke the tool correctly, though it leaves the sibling-boundary question unanswered.

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

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

Schema description coverage is 0%, so the description must carry the load, and it largely does: part_layer is described as an optional single-layer lookup with a defined fallback value (UNKNOWN_PART_LAYER), and country_code is specified as a 2-letter ISO code. It stops short of documenting name casing or format rules for part_layer ids.

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

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

The description gives a specific verb and resource ('Returns the available canonical part layers for territory construction') and even names concrete layer examples (us_zips, us_counties, ca_fsa). However, it never distinguishes itself from plausible siblings like query_parts or get_part_selection, so an agent must infer the boundary itself.

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

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

Usage is only implied through parameter behavior: call bare to get the list, pass part_layer for deeper metadata, pass country_code to filter. There is no explicit statement of when to choose this tool over query_parts or get_part_selection, nor any stated prerequisites.

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 beyond annotations with concrete behavior: a partial result object returns INVALID_REQUEST, dismiss=true hides the dock while retaining statistics, and it changes nothing in the Territory Solution. Annotations only declare the generic hint flags, so these additions carry real value; no mention of idempotency despite idempotentHint=false.

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 prerequisites, and each sentence adds distinct information (input requirements, modes, dismiss behavior, mutation scope, sibling routing). Slightly dense and run-on but no wasted filler.

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

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

For an 8-parameter tool with an output schema, the description covers inputs, error conditions, mode options, and side effects well. The undocumented roles/labels parameters and untested idempotency claim keep it from being fully 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?

With 0% schema description coverage the description must compensate, and it documents map_session_id, task_id/job_id, the analyses/tal_analyses/ts_identity shape, dismiss semantics, and enumerates presentation_mode values (single, compare, executive, diagnostic). Only roles and labels go unexplained.

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 ('Shows a completed analyze result in the open map's analysis dock') and explicitly distinguishes the single vs compare display contexts. An agent can tell this apart from siblings like analyze, get_map_visualization, and set_map_state.

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?

States prerequisites (map_session_id plus task_id/job_id or full result) and routes the agent to an alternative path ('analyze with analysis_panel=single fills the dock in the same call'). It lacks an explicit statement of when NOT to use this tool, but the context is clear.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description confirms this but goes well beyond: max_points capping semantics ('counts and sums always cover every inside point'), the multi-polygon counting rule, the overlaps field, default/max values, and precise error codes with returned available values. That is rich behavioral context an agent cannot get from structured fields.

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?

Purpose and scope are front-loaded in the first sentence, and nearly every clause carries operational detail (overlap rule, error codes, caps). It is dense and reads as one long run-on paragraph without visual grouping, which slightly hurts scannability, 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?

An output schema exists, so return values need not be re-explained, and the description still covers errors, defaults, counting semantics, and selection fallbacks. An agent has everything needed to call this 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 carries the full burden and it does: it explains map_session_id/ts_handle requirements, tal_id resolution fallback, territory_id (leaf, id or exact unique display name), territory_ids, point_layer defaulting, point_filter syntax with an example, metrics fallback, and max_points bounds. All nine parameters are given meaning beyond their bare titles.

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 ('Lists') plus the exact resource ('which account points from one point layer fall inside a territory polygon or drive-time area'), and even names the return contents (point ids, properties, point_count, metric sums). An agent can distinguish it from analyze and query_parts 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 explicitly routes the alternative case ('Territory statistics without the point list come from analyze') and spells out the selection rules for each scoping parameter: territory_id vs territory_ids vs both omitted (every leaf in the TAL), and point_layer omitted (the sole layer with points). Nothing is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety bar is covered. The description adds genuinely new behavior: results omit geometry, the parameter mutual-exclusion failure mode, and that results are paged via page_token.

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 what is returned and what is excluded, then the constraint, then paging. No filler or repetition 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?

An output schema exists, so return-value detail is not required, and the description supplies the essentials: no geometry, mutual exclusivity, and pagination. The only real gap is max_results/default page size behavior, which an agent would need for paging 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 carries the full burden, and it explains the filter/part_ids duality with a syntax example and page_token's role. max_results is never mentioned, leaving one of five parameters undocumented anywhere.

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

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

States a specific verb (returns attributes), resource (parts of a part layer), and an explicit scope exclusion ('no geometry'). It also names the discovery path (list_part_layers or ezt://part-layers), which separates it from the sibling that lists layers rather than parts.

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 operating rule: exactly one of filter or part_ids, and neither/both yields INVALID_REQUEST, including a filter example ({state_abbr: TX}). It does not compare against other retrieval siblings such as get_part_selection or points_in_territory, so routing guidance is clear but not exhaustive.

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?

Well beyond the annotations (destructive/not idempotent), it discloses the mutation model, optimistic concurrency via expected_revision with STALE_TS_REVISION, specific failure codes (UNKNOWN_TERRITORY_ID, AMBIGUOUS_TERRITORY with available_leaf_territories), the effect of remove_empty_territories, the returned task and map repaint, and the analyze refresh 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?

Front-loaded with the core action, then the input shapes, error semantics and side effects. Dense but every clause earns its place; slightly long single-paragraph form costs it the top mark.

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 spelled out, yet it usefully notes a task is returned and the map repaints. Error, concurrency and alternative-tool behaviour are all covered; only the unmentioned part_layer keeps it from being fully complete for an 11-parameter 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?

With only 9% schema coverage the description has to carry the load, and it does for moves, part_ids, realign_operation, ts/ts_handle/map_session_id, expected_revision, to_territory_id (leaf id or exact unique display name) and remove_empty_territories. It is not exhaustive: part_layer is never mentioned and the repair_policy nuance is left to the schema.

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

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

States a specific verb (moves) plus resource (ZIPs/parts between territories within one alignment, tal_id) and explicitly scopes it as 'a ZIP move'. This is clearly distinguishable from siblings like territory_merge, territory_split and territory_rebalance, which are bulk topology operations.

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 routes the agent through the selection workflow (get_map_selection for a committed selection, request_part_selection to have a person pick parts) and names the alternative input shape (realign_operation with part_ids). It does not, however, state when to prefer realign over sibling operations like territory_rebalance or territory_merge.

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?

Beyond the annotations (destructiveHint=true, idempotentHint=false), the description discloses a concrete failure mode (STALE_TS_REVISION when master changed) and a concurrency constraint ('merges apply one at a time'). That adds real behavioral value the annotations don't carry, though it omits permissions/auth and reversibility details.

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 action, followed by requirements and the failure/recovery note. No filler, though the parenthetical naming of 'proposal Territory Solution' is slightly dense.

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 described, and the key error is covered. But for a destructive 8-param mutation with nested objects and 0% schema coverage, the description leaves most parameters and any permission/precondition context undocumented, so it is only adequately 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 0% across 8 parameters, so the description must compensate, yet it names only branch_metadata and expected_master_revision. The six remaining params (master_ts, proposal_ts, map_session_id, master_ts_handle, proposal_ts_handle, expected_master_content_hash) are left entirely unexplained, including when the handle variants are used.

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

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

The description gives a specific verb+resource: 'Merges an edited branch... back into the master', and explicitly identifies the branch as the proposal from extract_tal_branch, which separates it from its counterpart sibling. It stops short of distinguishing itself from other mutation siblings like territory_merge.

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 embeds the tool in a workflow by naming extract_tal_branch as the source of the branch and states the recovery path when STALE_TS_REVISION is returned (a fresh extract is needed). It gives clear context but no explicit when-not-to-use or alternative-selection rule.

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 only supply low-information mutation hints (readOnly=false, idempotent=false), so the description carries real weight: 15-minute URL expiry, 1-hour default handle TTL, single-use handle semantics, and two concrete error codes (UNREADABLE_FILE_REFERENCE, UPLOAD_TOKEN_EXPIRED) with the re-issue behavior. This is exactly the disclosure the annotations cannot 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?

Front-loaded with purpose and return values before the mechanism details; nothing is filler. The second and third sentences are densely stacked with parentheticals, making them slightly run-on, but the size is justified by the tool's four-path complexity.

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 return formats need not be restated, yet the description still calls out the key returned fields. Combined with error codes, TTL defaults, and per-path constraints, an agent has everything needed to stage rows correctly and hand off to ingest_accounts.

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: csv_file (host file, local path fails), csv_text (raw CSV, 16 MB cap, newlines preserved), rows (chunks appended via upload_handle), upload_handle (single-use). ttl_seconds is only implied by the 'expires after 1 hour by default' clause rather than named, leaving one parameter short of fully covered.

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

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

States a specific verb and resource ('Stages account rows for ingest_accounts') plus the exact artifacts returned (upload_handle, csv_headers, suggested_ingest args, geocode_plan). It is cleanly distinguished from its consumer sibling ingest_accounts, which claims the handle.

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?

Names the consuming tool and lays out four ingestion paths with selection conditions ('POST ... fastest for large files'; csv_text 'up to 16 MB'). Missing an explicit when-not-to-use rule, but the workflow placement relative to ingest_accounts 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?

Annotations cover the safety profile (readOnly=false, idempotent=false, destructive=false), and the description adds real operational context beyond them: single-use handle, 1-hour default expiry, a 15-minute unauthenticated POST window, and automatic legacy-column mapping. These are the traits that change how an agent sequences the call.

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 before mechanism, and every sentence carries load: input routes, column mapping, redirect rule, handle lifecycle. No filler or restatement of the tool 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 staging tool with no required params and an output schema, the description supplies everything an agent needs: the four input paths, the target build (direct_build), the redirect case, and handle expiry. Return values are covered by the output schema and reinforced by the upload_handle mention.

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: csv_text behavior (newlines preserved), upload_handle for chunked appends, and the expiry semantics behind ttl_seconds. The assignments array is only implicitly referenced as 'assignment chunks', leaving the fourth input route slightly less precise than the others.

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 (stages) and resource (part-to-territory assignment rows), with a concrete example and the return value (upload_handle). It also explicitly distinguishes itself from the sibling request_account_upload, so an agent can separate the two 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?

Says this feeds direct_build as a consumer, enumerates the four accepted input routes, and gives an explicit when-not with the alternative ('A file of locations rather than assignments is redirected to request_account_upload'). Nothing about selection is left to inference.

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

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

Goes well beyond the annotations by disclosing the async task flow: it returns selection_task_id, that get_part_selection reports awaiting_user_selection then committed/expired/cancelled, and that the response carries recommended_poll_delay_ms. It also flags the important operational fact that the commit happens on the map, not in chat.

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

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

A dense single paragraph with the core action front-loaded and no filler sentences. Some clauses (poll delay, status enumeration) could be tightened but every statement carries useful information.

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

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

Given an output schema exists, return values need not be explained, and the description still supplies the full task lifecycle and polling guidance. It is largely complete, though the many undocumented parameters leave some invocation detail to 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?

With 0% schema coverage the description must carry the parameter burden. It meaningfully explains part_layer, purpose (realign/new territory/plain list), and how realign_operation and destination_territory_id pre-set a realign, but leaves ts, prompt, user_id, active_tal_id, new_territory, expiry_seconds, and remove_empty_territories undocumented.

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

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

States a specific verb+resource ('puts the open map into select mode on a part_layer') and the goanpurpose (realign, new territory, plain list). It is clearly distinguishable from the siblings get_part_selection and get_map_selection, which it names.

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?

Explains when to use it (letting the person adjust boundaries by picking parts) and routes one specific case to an alternative ('A selection the person started from the map legend is read with get_map_selection'). It does not, however, state explicit exclusions or prerequisites for the other paths.

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 (which only flag non-readOnly, destructive, non-idempotent). It discloses the UNDECLARED_FIELD error path, the CLARIFICATION_REQUIRED behavior with the specific missing inputs, the async 'returns a task' contract, that never_visit_values are excluded, and that bucket_workload_hours is a distinct measure from territory/route workload.

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?

Dense but front-loaded: the core action leads, then requirements, errors, and edge-case distinctions follow. Given 20 parameters it is economical, though the parenthetical-laden run-on style makes it harder to scan than it needs to be.

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

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

With an output schema present, it correctly omits return-value detail (aside from noting it returns a task). For a complex, 20-param, destructive scheduling tool it covers the critical prerequisites, failure modes, and sibling distinctions, but the unaddressed optional parameters leave a real gap.

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

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

Schema description coverage is 0% across 20 params, so the description carries the full burden. It meaningfully documents point_layer, visit_frequency_field, dwell_time, daily_capacity, contractors, frequency_unit, never_visit_values, and visit_constraints/horizon_start_date, but leaves ts, horizon, objective, ts_handle, map_session_id, schedule_label, emit_visit_layer, visit_layer_name, expected_revision, max_buckets_per_day, and cadence_flexibility_pct unexplained — roughly half the surface.

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 (schedules recurring visits), then specifies the mechanism: expanding each account's cadence across a horizon and packing visits into daily buckets under a technician-day cap. It explicitly differentiates itself from siblings by noting that auto_build and cluster_points divide accounts among people instead.

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 clear conditions and prerequisites: point_layer must be ingested with the cadence column declared, and missing dwell or capacity yields CLARIFICATION_REQUIRED with the question. It also routes follow-up work ('calculate_route over one bucket_id drives that day') and contrasts with auto_build/cluster_points, though it stops short of an explicit when-to-use-this-vs-alternatives rule.

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 destructive=true, readOnlyHint=false, idempotentHint=false, and openWorldHint=false, and the description is consistent with them while adding real behavioral context: it enumerates the terminal fit statuses, the SEED_TARGET_UNDERSHOT/OVERSHOT and SEED_PART_ASSIGNED/UNDECLARED_FIELD failure modes, the 'parts already in that alignment are never taken' blocking rule with blocked_part_count/seed_offset_km, and the side effect of repainting the open map. It stops short of stating permission or auth requirements, 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?

The purpose is front-loaded in the first sentence and every subsequent sentence carries payload (target grammar, fit statuses, error codes, blocking semantics, return shape). It is a single dense semicolon-heavy block, though, which makes the error/warning content harder to scan than a short structured list would be.

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, nested-object, open-world mutation with an output schema present, the description covers the operation's intent, target semantics, scoping, failure modes, and side effects well enough to call it correctly, and it need not re-explain return values because an output schema exists. The remaining gap is the handful of optional parameters with no description anywhere (user_id, tal_label, part_ids, max_parts, territory_name).

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% on 14 parameters, so the description carries the full burden and largely meets it: it gives the seed shape ({longitude, latitude}) and the target union ('{type: location_count, value: N}' or '{type: metric_sum, field: <declared metric>, value: X}'), plus the roles of part_layer, point_layer, tal_id, part_scope/part_filter, ts_handle, and map_session_id. It leaves user_id, tal_label, part_ids, max_parts, and territory_name unexplained, so it compensates for the critical nested objects but not all parameters.

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

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

The description names a specific verb and resource ('Grows one territory outward from a seed over a part layer until it holds a target') and defines the target grammar, so the action is unambiguous. It does not, however, distinguish itself from look-alike siblings such as auto_build, direct_build, or create_territory_from_parts, so an agent must infer the boundary.

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 constraints are implied rather than stated: 'One seed per call' and 'part_scope=explicit with part_filter confines growth to an area' tell the agent how to scope a call, and the conditional spawn point ('leaf of tal_id, or as a new alignment') signals when each mode applies. There is no explicit when-to-use-this vs auto_build/direct_build guidance, leaving selection among the territory-building siblings to inference.

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

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

Annotations only say readOnlyHint=false, idempotentHint=false, destructiveHint=false; the description adds genuinely new behavior: changes are session-scoped and do not touch the Territory Solution, render_ack is read at publish time so one-version-behind sent_unconfirmed is normal, render_ack_hint tells whether to reread or resend, camera persists until changed, and alignment switching does not refit. That is deep operational context an agent cannot get from structured fields.

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?

Dense but front-loaded: the mutation summary comes first, then session-vs-durable scoping, then the ack/camera caveats. Each sentence carries distinct information, though the ack and camera sentences are tightly packed and could be sectioned more readably.

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-param session-mutation tool with an output schema present, the description supplies the critical operational context: session scope, ack timing semantics, and camera source handling. The remaining gap is enumerating valid 'mode' values and the pending_job_reference contract, which neither schema nor description covers.

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% with 6 params, so the description carries the burden and does add real value: center is ordered [longitude, latitude] and zoom is bounded 0-24, plus camera's source enumeration (requested, session, map_config, viewer_current). However, it never explains the 'mode' parameter's permitted values, the shape/meaning of pending_job_reference, or map_session_id, leaving half the parameters semantically opaque.

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 ('Changes the open map's session state') and enumerates the exact facets it mutates: mode, active alignment, pending job reference, camera. It explicitly contrasts itself with configure_map, so an agent can separate 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?

Gives a clear selection rule — this is session-only, while configure_map sets a durable default view — which is exactly the decision an agent faces between these siblings. It stops short of stating full when-not conditions (e.g., whether a session must already exist), so it is clear context rather than an exhaustive routing guide.

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 only declare readOnly=false, idempotent=false, destructive=false, openWorld=false; the description adds substantial behavior beyond that: hiding a part layer leaves territories unchanged, missing point layers are re-pushed (status=refreshed, render_ack), unsupported hides return HIDE_NOT_SUPPORTED with do_this_next, and the legend checkbox is a single-tab workaround.

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 scoping and routing intent is front-loaded, but the body is a single very dense run-on block mixing input selection, per-kind behavior, and return codes, making it hard to scan. Most sentences earn their place, but the packaging is not concise.

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 10-param mutation tool with an output schema and annotations, it stops short of re-explaining return values yet still discloses the key outcome codes (refreshed, render_ack, blocked_by, HIDE_NOT_SUPPORTED). The main gap is the three unmentioned concurrency/merge 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?

With 0% schema coverage and 10 params, the description carries the burden and covers the key ones: map_session_id (marked preferred), ts_handle, ts, overlay_kind (with its enum values), overlay_id, route_id ('targets one'), and implicit user_request. It leaves merge_strategy, expected_revision, and expected_content_hash undocumented, so it is strong but not complete.

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 pair (shows/hides), the resource (overlays on the open map), and enumerates the overlay kinds it handles (part_layer, point_layer, tal, route). It also distinguishes itself from siblings like delete_point_layer and configure_map by routing those cases explicitly.

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 when-to-use conditions: plain request ('add US zip codes', 'hide the zips') or overlay_kind+overlay_id, and states prerequisites ('point layers must already be ingested', routes must exist or blocked_by=needs_route). It names alternatives for cases it doesn't handle (delete_point_layer, configure_map).

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