EasyTerritory MCP

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

With no annotations, the description carries the full burden and does so well: it discloses live subphase publishing on Tasks/MC overlay, cooperative cancel, the shared next_action/sleep_ms poll loop, the rule against silently inheriting a cadence column, and protocol-version-gated in-band prompting vs legacy INVALID_REQUEST behavior. It omits the mutation/permission profile (whether the build overwrites existing territories) and any expected_revision concurrency semantics, keeping it out of the top band.

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

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

The tier and "When" clause are front-loaded and nearly every sentence carries actionable content (scope semantics, progress model, cadence rule, client compatibility). It is nonetheless densely telegraphic, with fragments like "That session is the TS" and opaque scenario codes (ACB-001..004, MC-011) that cost readability without adding selection value.

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

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

An output schema exists, so return values are already covered, and the description supplies everything else an agent needs for this complex 17-param builder: prerequisites, scope selection branching, progress/cancel behavior, cadence handling, and host-compatibility fallbacks. Nothing material to invoking it correctly appears to be missing.

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

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

Schema description coverage is only 6% across 17 params, so the description must compensate, and it explains roughly a dozen of them in prose: ts/ts_handle omission when a session id is set, part_scope default of bbox_intersect, part_filter/part_ids placement as top-level scope fields, grouping_field, part_layer, tal_label, visit_frequency_field and ignore_visit_frequency. It leaves the single required parameter (point_layer) and repair_policy/conflict_policy/expected_revision/guidance_handle unexplained, so the coverage gap is narrowed but not closed.

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 tier tag "Attribute Grouping Builder" plus "territories should mirror an account attribute column from CRM exports" states a specific verb (build) and resource (territories grouped by an account attribute), which cleanly separates it from auto_build, seed_build and direct_build siblings. It never states the purpose in one plain sentence, so it is clear but leans on the reader to assemble the meaning from fragments.

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

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

It gives an explicit "When" condition (territories should mirror a CRM attribute column), prerequisites (ingest_accounts with grouping column, part_layer chosen, viewer connected), and a concrete routing rule for the common ambiguity: naming a state/region requires part_scope=explicit with part_filter, not bbox_intersect. It also points to the follow-up (analyze + load_analysis_panel) and names auto_build as the shared poll-loop peer.

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

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

With no annotations, the description fully carries the behavioral burden and does so richly: it discloses that workload omission still returns counts/metrics (workload_total null, never drive-only hours), that undeclared columns fail with UNDECLARED_FIELD, that metric cells are parsed leniently, that workload_total is in minutes while hours only come from grids, and that panel push duration is not proof the dock opened. This is far beyond what a schema could 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?

The guidance is valuable but delivered as a dense wall of text with repetition — workload omission is re-explained multiple times, dock behavior is revisited, and 'never invent a default (including 30 minutes)' restates an earlier point. Some length is justified by tool complexity, but it is not tightly front-loaded or easily scannable.

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?

Because an output schema exists, the description is not obligated to describe return values, and it still covers prerequisites, the failure mode (UNDECLARED_FIELD), units, and panel-state semantics comprehensively. The gap is the unexplained params, but for a tool of this complexity the behavioral coverage is nearly sufficient on its own.

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 15 parameters, so the description must compensate and it only partially does. It explains ts/ts_handle/job_id inputs, metrics semantics (omit for all declared columns, bare strings vs {field,label,type}), dwell_time, tal_ids in workload_omitted, and analysis_panel=single with map_session_id. Eight parameters (scope, max_depth, part_layer, compare_tals, guidance_handle, hypothetical_moves, visit_frequency_field) receive no explanation at all.

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 scope: '[Tier 1 — Analysis] When: balance diagnostics, cross-TAL comparison, or post-mutation facts,' which clearly identifies the resource and operation. It is distinct from analyze_routes by implication but never explicitly contrasts with sibling analysis tools. An agent understands what it does, though not the full boundary against nearby 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?

It states explicit trigger conditions (balance diagnostics, cross-TAL comparison, post-mutation facts), prerequisites ('TAL exists; re-run after any TAL or point change (I-2)—never treat stale analysis as current'), and an alternative path ('Otherwise pass the full Analyze result ... to load_analysis_panel'). There is also an explicit prohibition: 'Do not ask for dwell before the first analyze just to avoid the note.'

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

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

With no annotations, the description carries the full burden and does so: it declares synchronous execution (no task_id), the CLARIFICATION_REQUIRED/needs_dwell failure mode for unresolved dwell, and the FACTS-ONLY contract (no capacity, headroom, ranking, or overloaded flag). It also warns against summing/comparing its hours with cluster/territory workload figures, which is behavior beyond any structured field.

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 When/Prerequisites and sequences the guidance logically, and nearly every sentence adds decision-relevant content. It is nonetheless dense and long, with some quantity-distinction caveats that verge on repetition, so it stops just short of optimal concision.

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 still clarifies the workload math and quantity meanings where they could be misused. For a fact-reporting tool with 5 inputs and no required params, every decision-relevant piece an agent needs is present.

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 5 params, so the description must compensate. It does explain map_session_id vs ts_handle ('map_session_id preferred') and dwell_time semantics (one dwell per stop, charged twice for a circuit), but route_ids is only touched obliquely and guidance_handle is never explained, so it only partially fills the gap.

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

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

States a specific verb+resource ('per-route numbers for routes calculate_route already drew') and enumerates exactly what it returns: drive hours, dwell hours, route_workload_hours, stop coordinates, centroid, bbox. It explicitly differentiates itself from the analyze sibling ('analyze is TAL/part-grained') and from territory/cluster workload quantities, so an agent can place it 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 an explicit 'When' trigger with concrete example questions, states prerequisites (a route must exist; dwell confirmed unless already stored), and lists anti-patterns ('do NOT call analyze for routes', 'do NOT feed these hours into auto_build, territory_rebalance'). It also names the correct follow-up path (re-run calculate_route with the route_id) and a scenario code, leaving nothing 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?

With no annotations, the description carries the full burden and does so: it discloses the server-side rejection without resolved dwell_time (CLARIFICATION_REQUIRED), elicitation vs legacy host behavior, long-partition subphase publishing and lease renewal, the NATIONAL_PART_SCOPE warning, and that it appends a TAL rather than replacing alignments. These are non-obvious behavioral traits an agent could not infer from the schema.

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

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

It is front-loaded with 'When:' and organized into condition/action blocks, which helps. However the text is very long and repetitive — the dwell-time instruction is restated several times, and multiple parenthetical warnings dilute the key directives, so it is informative but not tightly written.

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 18-parameter remote build job, the definition covers the prerequisites, execution gate, dwell/visit-frequency prerequisites, error paths, polling expectations, scope defaults, and post-build analysis steps. With an output schema already handling return values, nothing essential 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 only 6% across 18 parameters, so the description must compensate heavily, and it does for the critical ones: build_mode mode enum values, objective.workload_bias=100 semantics, dwell_time scalar vs field shapes, top-level part_scope/part_filter placement, visit_frequency_field and ignore_visit_frequency. It leaves several parameters undocumented (repair_policy, expected_revision, guidance_handle, part_ids), so it falls short of full coverage.

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

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

It names a specific verb and resource ('partition account points into N balanced territories over a part layer') and explicitly distinguishes itself from siblings, stating that direct_build is for known assignments and account_build is for grouping by attribute. An agent can identify the tool's role without opening the schema.

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

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

It gives an explicit execution gate ('after sizing, balance, dwell, and scope are known, call THIS tool immediately'), names what does NOT start a build (catalog search, get_guidance, polling Tasks), and routes the agent via workflow_advisor returning next_tool=auto_build. This is about as clear a when/when-not as possible.

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

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

No annotations are provided, so the description carries the full burden, and it delivers: API-key prerequisites, all-or-nothing quota semantics with the PROVIDER_QUOTA_EXCEEDED payload fields, async task_id + _meta.next_action flow, and 'no stop moves between sets' optimization guarantees. It also discloses the route_id add-vs-replace mutation behavior and the dwell double-charge caveat, which are non-obvious side effects an agent must know.

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

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

It is long, but front-loaded with the 'When:' trigger and organized under labeled sections (TERRITORY STOPS, ORDERED STOP SETS, ROUTE TYPES, MANY ROUTES, QUOTA), so most sentences earn their place. It is dense rather than bloated, though some quota/route_id detail 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?

Given an output schema exists (return values need not be explained) and 13 params with nested objects, the description covers workflow context, prerequisites, async behavior, quota failure mode, and multi-route map storage. An agent has everything needed to invoke it correctly and interpret its lifecycle.

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 13 params, so the description must compensate and does so for the critical ones: route_type values ('circuit'/'tour'/'open_tour'), start constraints (exactly one stop), stop_sets ordering, order, group_by_field, filter.territory_id, route_id reuse semantics, and dwell_time provenance. However, several params (depart_at, travel_mode, include_geometry, ts_handle, guidance_handle, route_label) are never addressed, leaving the coverage gap only partially closed.

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 ('routes and sequences existing stops', 'drive a list of stops in the best sequence') and immediately bounds the scope ('never creates or rebalances territories'). It explicitly distinguishes itself from siblings like schedule_visits, analyze_routes, delete_route, and auto_build, so an agent can select 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?

Opens with a 'When:' clause covering the trigger scenarios, then names the disambiguation case (visit-frequency column → confirm against schedule_visits) and the do-not-use case (territory creation/rebalancing). Prerequisites and alternatives are both stated, leaving little 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?

With no annotations, the description carries full behavioral burden and does so richly: it discloses the destructive side effect ('replaces the layer's existing color classification'), unmatched-point handling, the 10,000-point cap after filtering, seed/layer invariants ('seeds carry NO workload and are never members'), and named failure modes (EMPTY_POINT_FILTER, UNKNOWN_POINT_PROPERTY, INVALID_REQUEST with blocked_by=seed_count_mismatch). This is well beyond what structured fields 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?

The purpose and destructive write are front-loaded with a tier label, and given the tool's genuine complexity most sentences earn their place. However, it is a dense single block with seeding, subset, error, and example concerns interleaved rather than clearly sectioned, which hurts scannability for a 16-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 needn't be detailed, yet the description still points at result.seed_summary.groups and the groups list (group_id, point_count, workload_hours, point_ids). Combined with guidance handle, atom reference, and scenarios, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 0% across 16 parameters, so the description must compensate and largely does: build_mode's allowed modes, objective/workload_bias, dwell_time's scalar/value/unit shape, point_filter key semantics, seed_point_layer constraints, seed_attraction's 0-100 default and meaning, and group_field's default are all explained. It leaves metric_fields, map_session_id, guidance_handle, expected_revision, and group_label_prefix undocumented, so it falls short of full coverage.

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

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

The first sentence states a precise verb and resource: 'Partition one ingested point layer directly into balanced point groups with CCPD,' and immediately disambiguates scope with 'without using ZIPs/counties or creating a TAL.' It explicitly routes away from siblings ('Use auto_build for territories', 'those belong to ZIP/part tools'), so an agent can distinguish it without opening any schema.

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

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

Explicit when-to-use, when-not, and prerequisite guidance is present: prerequisite 'ingest_accounts completed', subset usage via point_filter with an example, and prohibitions ('Do not pass part_filter or part_scope', 'Do not cluster the national layer', 'never a second color classification'). It also tells the agent which sibling to use for territories, leaving nothing 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?

With no annotations, the description carries the full burden and does so richly: it discloses persistence ('persists to ts.properties.map_config.project_name'), emitted events ('emits config_changed so a linked session refreshes the heading in place'), server-side computation of breaks with returned per-class counts, replace-not-merge semantics ('a second color entry replaces the first'), clear:true behavior, method defaults, categorical missing-value handling ('Ungrouped class'), and camera side effects ('jump an open MC when included on this call; Monica's pan is not captured'). It even warns against a stale ts_handle stripping points/part layers.

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

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

It is front-loaded with clear inline labels ('When:', 'POINT SYMBOLOGY:', 'Next:', 'Scenarios:'), which helps navigation, but it reads as a dense wall of text ballooning well past the param list, and some content repeats (config_changed is explained twice). For a tool this complex much is justified, yet trimming redundancy and adding line structure would improve scannability.

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, no annotations, and an existing output schema (so return values need not be documented), the description covers triggers, prerequisites, side effects, defaults, and misuse routing at a high level. It falls short only on the unexplained concurrency parameters (expected_revision, expected_content_hash) and merge_strategy, which matter for safe repeated invocation.

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

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

Schema description coverage is 0% across 16 parameters, so the description must and largely does compensate: it defines point_layer_classifications entry structure (point_layer, field, method, class_count range 2-12, channel, optional colors/sizes/shapes, style), supported shape aliases, and the meaning of classification-vs-point_layer_classifications, center ([longitude, latitude]) and zoom (0-24). However merge_strategy, expected_revision, expected_content_hash, and guidance_handle receive no explanation, leaving concurrency/optimistic-locking semantics undocumented.

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

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

The description opens with a bracketed tier/role ('Durable Map Config') and an explicit verb list ('set or update project_name, loaded_part_layers, active_part_layer, active_tal_id, point_layer_classifications, classification, presentation, center, or zoom on the TS'), so the resource and scope are unambiguous. It also names the sibling it is NOT ('Not the entry tool for browsing a TS — that is get_map_visualization (I-1)'), letting an agent separate it from sibling tools without opening schemas.

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

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

There is an explicit 'When:' trigger, prerequisites ('map_session_id, ts_handle, or inline ts; points already ingested before point_layer_classifications'), follow-on guidance ('Next: build or analyze; if active TAL changes, re-run analyze then load_analysis_panel'), and an explicit anti-pattern ('never export GeoJSON, compute breaks client-side, and repost a TS'). It also routes a misuse case ('a point-layer-targeted classification is routed to symbology with a warning'). Usage is fully specified.

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

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

With no annotations, the description carries the full burden and delivers: the server loads the session TS, appends a new TAL, and rebinds the session before map_refresh; new TALs do not inherit dwell_time; missing dwell causes workload_omitted in Analyze; declining an in-band dwell prompt still permits creation (HITL-038). These are genuine side effects and failure semantics beyond any structured field.

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 useful headers (When/Prerequisites/Next/Dwell/Scenarios), but the body is very dense and acronym-heavy (TAL, TS, MC, RL, HITL, DWELL), which taxes readability. Several clauses about downstream Analyze behavior and prompting could be tightened without losing meaning.

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

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

An output schema exists, yet the description still usefully names key return fields (created_territory.territory_id, leaf_territories, selection_summary, map_refresh.notified) and the realignment rule that must use territory_id rather than an invented shorthand. It covers the workflow end-to-end; the remaining gap is the five undocumented input parameters.

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

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

Schema coverage is 0% across 10 parameters, so the description must compensate. It meaningfully explains part_ids, part_layer, map_session_id, dwell_time and the display-only nature of territory_name, but says nothing about ts, tal_id, territory_path, conflict_policy, or guidance_handle — roughly half the 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 specific verb+resource+scope: 'create or update one leaf territory from committed part IDs', and tags the trigger conditions (manual MC-005 build, RL-011/012). It is clearly distinguishable from siblings like auto_build, direct_build, realign and territory_merge, which are named or implied by contrast.

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

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

Explicit 'When:', 'Prerequisites:', and 'Next:' sections, plus a negative instruction ('do not call get_map_visualization just to show the new territory') and a routing rule for when to call it (rebind_required / notified=false). Alternatives such as analyze and realign are named with the condition that selects them.

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

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

No annotations are provided, so the description carries the full behavioral burden and does so richly: idempotent semantics (already_absent=true, no error), the AMBIGUOUS_ROUTE error with matching_route_ids, synchronous execution (no task_id), and a verification step via the map legend.

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 'When' clause comes first, followed by prerequisites, exclusions, and error behavior. Every sentence adds value, though the '[Tier 2 — Delete Route]' prefix and the trailing 'Scenarios: RT-010' are metadata noise.

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

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

An output schema exists, yet the description still covers the meaningful return signals (already_absent, AMBIGUOUS_ROUTE). Combined with prerequisites and verification guidance, an agent has everything needed to invoke and interpret the call.

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

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

Schema description coverage is 0%, so the description must compensate. It explains route_id (or exact unique label), the preferred map_session_id vs fallback ts_handle, but guidance_handle is never mentioned, leaving one of four 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+resource (delete/drop a whole route) and explicitly scopes what it is not: removing a single stop. It names the sibling that handles that case (calculate_route), so an agent can distinguish the two without opening schemas.

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

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

Provides explicit 'When' triggers with example utterances, prerequisites (map_session_id preferred else ts_handle, plus route_id or a unique label), and a clear exclusion routing single-stop removal to calculate_route. Alternatives and edge cases are enumerated.

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

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

With no annotations, the description carries the full burden and does so: synchronous execution (no task_id, no progress overlay), what is preserved (points, overlays, routes), the post-condition of active_tal_id, and the idempotent already-absent=true outcome plus AMBIGUOUS_TAL error path.

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

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

Dense but front-loaded, leading with tier and action, then when/prerequisites/exclusions/post-conditions. Nearly every clause carries routing or behavioral value, though the user-language list and scenario IDs add bulk that a tighter phrasing could absorb.

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 delete tool with no annotations, the description supplies prerequisites, side effects, preservation guarantees, error semantics, and follow-up steps. Because an output schema exists, return-value detail is not required, and nothing an agent needs to invoke correctly is missing.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the role and precedence of map_session_id vs ts_handle and that tal_id accepts an exact unique label, which is meaningful beyond the schema. It does not mention guidance_handle at all, leaving one of four params 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 ('wipe one whole Territory Alignment Layer') with scope, and explicitly distinguishes itself from the sibling delete_territory ('NOT for deleting one leaf territory'). An agent can route correctly 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?

Names when to use it (including colloquial user phrasings), explicit prerequisites (map_session_id preferred, else ts_handle, plus tal_id), and an explicit when-not ('Do NOT N× delete_territory'). Alternative tools for the follow-up (auto_build/account_build/direct_build) are named.

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

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

No annotations exist, so the description carries the full burden and does so well: it discloses idempotent behavior ('Already-absent territories return ok with already_absent=true (no job)'), that a follow-up Tasks operation must be polled and its result called once, a verification step against both legend and canvas, and that geography-only deletes skip Analyze. This is unusually rich behavioral context for a mutation tool.

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

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

Front-loaded with the When clause, prerequisites, prohibitions, and next steps in a tight sequence. It is dense and long, but nearly every clause carries operative information (idempotency, verification, engine identity); a small amount of scenario-tag noise ('feedback delete-territory, RL-013 wrapper, T-087 last-leaf paint clear') is the only padding.

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

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

An output schema exists so return values need not be explained, and the description still adds the post-call workflow (poll Tasks, call result once, verify legend AND canvas). The only completeness gap is the four undocumented optional parameters, which matters for a 9-parameter mutation tool.

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

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

Schema coverage is 0% across 9 parameters, and the description compensates well for ts/ts_handle/map_session_id, tal_id, and territory_id (including valid sources for leaf ids and a warning against invented shorthand). However part_layer, repair_policy, guidance_handle, and expected_revision are never mentioned, leaving four 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 precise verb+resource ('delete one leaf territory from an existing TAL') and immediately distinguishes itself from delete_tal and from auto_build. It also names the underlying engine (Realign remove_parts + remove_empty_territories), so the agent knows exactly what operation is being performed.

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

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

Explicit When clause, explicit prerequisites (one TS reference, tal_id, territory_id), explicit exclusions ('Do NOT invent part_ids or call auto_build', 'never N× this tool' for wiping a TAL), and an explicit routing rule to delete_tal. It even tells the agent to ask when the territory reference is ambiguous.

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

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

With no annotations, the description carries the full burden and does a solid job: it discloses legacy auto-mapping behavior, the default duplicate_part_policy=keep_first, upload-handle provenance (aup_...), and prerequisites (part_layer chosen, viewer connected). It does not, however, state mutation semantics such as what existing territories are replaced or why expected_revision matters (optimistic concurrency), leaving a gap for a write operation.

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

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

Front-loaded with the 'When:' trigger, followed by preconditions, exclusions, next steps, and scenario codes. Dense but each clause carries routing value; the scenario/Tier/MC references add mild clutter without much agent-facing benefit.

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

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

An output schema exists, so return values need not be described. The gap is on the input side: for a 13-parameter mutation with zero schema descriptions, the definition leaves several parameters and the assignments-vs-handle distinction unexplained, so it is not fully complete for correct invocation.

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

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

Schema coverage is 0% across 13 parameters, so the description must compensate and only partially does: it clarifies assignments_handle format/origin, part_layer, ts/ts_handle optionality, and duplicate_part_policy. Several parameters remain undocumented (repair_policy, missing_part_policy, expected_revision, map_session_id, guidance_handle, the assignments array, tal_id/tal_label), and the relationship between the assignments array and assignments_handle is never explained.

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

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

States a specific action with scope: building a TAL from explicit part-to-territory assignments, tagged as the 'Known Assignments Builder'. It immediately distinguishes itself from siblings like ingest_accounts, auto_build, and account_build by naming each and the condition that selects 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?

Explicit when-to-use (user has explicit part-to-territory assignments, spreadsheet/legacy/hierarchical) plus three explicit 'Not for X—use Y' exclusions naming the correct alternatives. Prerequisites and follow-on steps are also 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?

With no annotations, the description carries the full burden and does so well: it discloses that routing is static keyword-based with no compute ("Prerequisites: none"), enumerates the return fields, and crucially explains that guidance is inlined so "you do NOT need a second resources/read." That behavior/latency note is exactly the kind of trait structured fields don't 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 tier tag, trigger, and prerequisites, which is good. But the body is a dense wall of run-on parentheticals (isochrone, periodic-scheduling, push/pull-to-designer) with no formatting breaks, and the trailing "Scenarios: AB-016, ACB-003, wrong-build-tool" is cryptic and hard to act on, so size partly works against it.

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

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

For a high-fan-out router, it covers purpose, trigger, prerequisites, routing branches, and return contents comprehensively, and it even pre-empts the output-schema lookup by describing returns (though an output schema already exists, so that is redundancy rather than a gap). The only meaningful hole is that its own two input parameters remain unexplained.

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

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

Schema coverage is 0% and neither parameter is documented: the description never explains what `user_request` should contain or what shape/keys the free-form `context` object expects. The mentions of "required_inputs" and "clarifying_questions" describe outputs, not inputs, so the description does not compensate for the coverage gap.

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

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

States a specific role ("Router / deterministic entry point for ambiguous or open-ended territory requests") and enumerates exactly which workflows it disambiguates (auto_build vs account_build vs direct_build, realign, isochrone, periodic-scheduling, push/pull-to-designer, etc.), so its function is unmistakable. It does not, however, differentiate itself from adjacent guidance/routing siblings such as workflow_advisor or get_guidance, which is the one clarity gap.

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

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

Gives an explicit trigger ("When: the user's goal or build type is unclear and you want the correct workflow before acting") plus a scoping adjective ("ambiguous or open-ended") that implies the when-not case. It also names the concrete alternatives for each ambiguous scenario, effectively routing the agent to the correct sibling.

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

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

With no annotations, the description carries the behavioral burden and does disclose important traits: it is a mandatory gate, requires a prior session id, unblocks the rest of the pipeline, and works identically across in-chat and map_url surfaces over SSE. It does not say what happens on timeout/failure or how wait_seconds/poll_interval_ms affect blocking, which is a real gap for a gating tool.

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

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

Front-loads the most decision-relevant information (When/Prerequisites/Next) in a labeled, scannable structure with no filler sentences. It loses a point for opaque references ('Tier 1 — MC-First Gate', 'Scenarios: MV-001, I-1') that add tokens without conveying meaning to an agent.

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 description supplies prerequisites, sequencing, and surface behavior adequate to call the tool correctly. The main shortfall is the untouched parameter semantics, which leaves timing behavior (wait_seconds, poll_interval_ms) undefined.

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 all 4 parameters, so the description must compensate. It only identifies the origin of map_session_id (from get_map_visualization); wait_seconds, poll_interval_ms, and guidance_handle are entirely unexplained in both schema and description, leaving their timing/behavioral effect 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?

The description places the tool precisely in a workflow (a Tier 1 gate that runs after get_map_visualization and before compute/build/analyze/selection work), so an agent can distinguish it from siblings like configure_map or analyze. The specific action (verifying/awaiting a connected human viewer) is implied by the name and the 'Next: ... once viewer_status.connected' phrase but never stated outright, and 'MC-First Gate' is opaque jargon.

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

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

Explicit When, Prerequisites, and Next clauses define exactly when to invoke it and what condition (viewer_status.connected) releases the workflow. It also gives a clear exclusion — 'Do not skip it on an Apps host' — and names the follow-on tools (ingest, configure_map, build, realign, analyze).

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

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

With no annotations, the description carries the full burden, and it does disclose a critical behavioral caveat: it returns no edges unless the pack ships a _graph.yaml, plus that traversal is bounded by depth hops. It does not mention permissions or performance, but the empty-result condition is the key operational fact an agent needs.

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

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

Two front-loaded sentences with zero filler: the first states purpose and scope, the second states the failure condition. Every sentence 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?

An output schema exists so return-value shape need not be explained, and the description covers the main input plus the important empty-result caveat. The gap is the undocumented edge_kinds parameter, which is unaddressed in both description and schema.

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

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

Schema coverage is 0%, so the description must compensate. It explains file_path (topic file, with example) and depth ('up to depth hops'), but edge_kinds is never mentioned in the description or schema, leaving one of three parameters 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 (traverse) and resource (EMEP knowledge graph) with a concrete example path, and distinguishes itself from retrieval siblings like ep_search and get_guidance by describing graph-hop traversal rather than search or direct fetch.

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 '[Knowledge Retrieval]' tag and 'find related guidance' phrase imply when the tool is useful, but it never states when to prefer it over ep_search, ep_list_topics, or get_guidance, nor any prerequisites. Usage must be inferred.

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

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

No annotations are provided, so the description carries the full burden. It discloses the grouping behavior and the enumeration of type categories, but says nothing about permissions, pagination, ordering, or result size. The return shape is covered by the output schema, which offsets some of the gap.

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

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

Two compact sentences, front-loaded with a category tag and verb. Every clause carries information (grouping axis, valid types, intended usage). No filler.

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

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

For a zero-required-parameter list tool with an output schema, the description provides the grouping model, the type vocabulary, and the intended discovery workflow. Remaining gaps (ordering, pagination, omitted-filter behavior) are minor rather than blocking.

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 schema defines no enum for `type`, so the description's enumeration ('concept, workflow, interface, troubleshooting, decision') is genuinely additive meaning. However, it doesn't state filter matching semantics or the behavior when `type` is omitted (absence of filter vs error).

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 (List) and resource (EMEP topics) and specifies the grouping axis (type) with the exact enum values. It names the sibling ep_search, giving an agent a clear anchor to distinguish it, though it doesn't contrast with other retrieval siblings like ep_graph_traverse or get_guidance.

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 says when to use it: 'to discover what guidance exists before ep_search, or to browse the pack.' This positions it as a precursor/discovery call. It lacks any when-not guidance or alternatives when a topic is already known.

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

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

With no annotations, the description carries the full burden and largely does: it discloses the return shape (ranked markdown chunks with source files), the requires_expanded flagging of pulled-in atoms, and graceful degradation to ezt://guidance/... resources. It does not state auth needs, rate limits, or retrieval latency.

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

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

Front-loads purpose, then usage trigger, then return behavior, then fallback, then examples. Dense but every sentence carries information; the trailing example list is the only part that 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?

An output schema exists, so return values need not be explained, and the description still adds the degradation and requires_expanded behaviors. However, for a four-parameter search tool with 0% schema coverage, the complete absence of parameter semantics leaves a real gap an agent must guess through.

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 four parameters (query, tags, type, max_results), so the description must compensate and does not. It never explains what tags/type filter on, what values are valid, or how max_results affects ranking/expansion.

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 ('Semantic search over the EZT MCP Expert Pack') plus the content types it covers (workflow guidance, concepts, interfaces, common mistakes). An agent can distinguish it from ep_graph_traverse, ep_list_topics, and get_guidance 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?

Explicit 'When' clause enumerates triggering situations (unsure which tool/order, hit an error, need domain context) and gives three concrete example queries. It names the fallback resources on unavailability, but does not explicitly contrast itself with sibling advisory tools like workflow_advisor or get_guidance.

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

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

With no annotations, the description carries the full burden and does so richly: async task_id pattern, that the result carries geojson_artifact {artifact_id, bytes} plus download_url requiring a Bearer API key, that there is never an inline multi-MB body, zip defaulting to gzip, and that styling ('paint') travels with the export. These are exactly the non-obvious behaviors an agent needs.

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

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

Front-loaded with the core purpose and scope, and dense but most sentences carry real information (async contract, artifact shape, Designer integration). It is somewhat overloaded with tangent detail (Designer REST/Agent/Projects endpoints) that burdens the core instruction.

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, annotation-free tool, the description covers sourcing, filtering, output format, download mechanics, and downstream reopen/import workflows. An output schema exists, yet the extra return-shape prose reinforces rather than pads, leaving no critical gap for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate, and it explains tal_ids/point_layers/route_layers scoping, zip=true/false semantics, include_points/include_routes toggles, and the three alternative source params. Only guidance_handle is left unexplained, so it nearly but not fully closes the coverage gap.

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

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

States a specific verb ('export'/'Materialize') and resource ('working GeoJSON FeatureCollection — territory polygons with part_ids, point features, and route paths + numbered stops'), and explicitly positions itself as 'the only Territory Solution export', distinguishing it from siblings. An agent knows exactly what it produces 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?

Names prerequisites (ts_handle, completed build job_id, or map_session_id), states the 'omit tal_ids/point_layers/route_layers for the full project' rule, and routes reopen flows to import_geojson and get_map_visualization. The async follow-up (Tasks next_action/sleep_ms) gives concrete when-and-how 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?

No annotations are provided, so the description carries the full behavioral burden and mostly does not. It implies isolation ('delegate opens MC on extract only') but never says whether extraction mutates or locks the source TS, what the returned extract contains relative to branch_metadata, or how exclude_locked/handles affect behavior. 11 parameters with 0% schema coverage make this a significant gap.

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

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

Telegraphic and front-loaded: the tier tag, When, Prerequisites and Next are laid out in order with no filler sentences. It is dense with domain jargon rather than purely concise, but every clause carries operational 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?

An output schema exists so return values need not be explained, but for a delegation/mutation-prone tool with no annotations, 11 undocumented parameters, and handle-based session state, the description omits too much: source-object side effects, what a valid delegate_ref is, and how the handles interact.

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?

Eleven parameters at 0% schema description coverage, and the description explains almost none of them. 'Branch rollup or path identified' loosely maps to branch_rollup_territory_id and branch_territory_path, and 'master TS' to ts/ts_handle, but delegate_ref, map_session_id, guidance_handle, expected_revision and expected_content_hash get no meaning at all.

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 ('extract' a TAL branch) and frames it as a Tier 1 delegation extraction of a regional subtree for bounded editing, which lets an agent place it in the workflow. However, the obvious counterpart/reverse operation (reintegrate_branch) is never named, so sibling differentiation relies on the agent inferring it from the tier label.

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 an explicit When ('senior planner sends a regional subtree to a delegate'), Prerequisites (master TS with hierarchical TAL; branch rollup or path identified) and Next step (store extract + branch_metadata, delegate opens MC on extract only). It is a real when-to-use block, but no when-not-to-use or named alternative is offered.

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

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

With no annotations, the description carries the behavioral burden and largely does: it discloses server-side CSV parsing/staging, that it can invoke ingest_accounts with map_session_id, that fixed-workload args are normalized to auto_build fixed_workload_target, and that modern vs legacy clients get different clarification behavior. It omits what happens to unhandled or ambiguous requests and any auth/side-effect scope, but the disclosed traits are substantial.

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

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

It is front-loaded with the use case, but it is a single dense block overloaded with opaque jargon ('HITL-025', 'CLARIFICATION_REQUIRED', 'protocol >= 2026-07-28', 'part_layer/tal_label') that an agent must parse rather than act on directly. Several clauses earn their place; the internal reference codes do not.

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

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

An output schema exists, so return values need not be described, but for a 9-parameter orchestrator with zero annotation coverage the description does not explain how the request string maps to the many sibling workflows, nor what the caller should do when the request is under-specified beyond the modern/legacy clarification note.

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 9 parameters, so the description must compensate. It explains request, csv_file, accounts_handle, assignments_handle, map_session_id, and ts_handle, plus args keys, but leaves state_facts and guidance_handle entirely unexplained, so a meaningful gap remains.

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

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

The description frames 'ezt' as a plain-language orchestrator that carries a goal to the right underlying action, and it distinguishes itself from siblings by telling the agent to prefer granular tools when the step is known. The verb is inherently generic ('orchestrate whatever the request implies'), so the resource is left implicit, but an agent can still tell what class of behavior to expect.

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

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

It gives explicit when-to-use ('when the exact granular tool is unclear or when a greedy/file-holding client wants to complete an action in one step') and an explicit when-not with the alternative ('Prefer granular tools directly when you know the step'). That is a complete routing 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?

With no annotations, the description carries the full burden and does so richly: it discloses monthly quota capping, that cache hits are free and must not be forced, the PROVIDER_QUOTA_EXCEEDED error with its limit/used/remaining/period_resets_at fields, and the operator-escalation path. Suffix guidance ('report those numbers instead of retrying') is exactly the kind of behavioral context annotations would otherwise 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-loads tier, when, and prerequisites before details, and every sentence adds operational value. It is dense with internal jargon (GC-001, ts_handle, MC-first) that a cold agent may parse slowly, but there is little outright 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 format need not be explained, and the description still points to result.geocoded_rows for chaining. For a 9-param quota-sensitive tool it is nearly complete, missing only explanations of several hint/session parameters.

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

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

Schema coverage is 0% across 9 parameters, so the description must compensate. It explains use_cache, force_regeocode, and accept_suboptimal_geocodes semantics plus the address column mapping for rows, but leaves region_hint, country_hint, map_session_id, min_confidence, and guidance_handle entirely 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+resource ('[Tier 1 — Geocode Only]... geocode addresses without full account ingest, or headless bulk geocode') and explicitly distinguishes itself from ingest_accounts. An agent can tell exactly what this tool does and how it differs from the sibling that also geocodes.

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

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

Gives explicit when ('when the user must verify geocode quality first'), when-not ('Prefer ingest_accounts for territory builds'), and prerequisites (none for headless; ts_handle + MC-first when human verifies). Alternative routing is spelled out, not inferred.

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

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

With no annotations, the description carries the full burden and does so: it declares read-only, discloses that the handle is a rotating code required by territory/map tools, and notes that per-tool rules and workflow essays live elsewhere. These are non-obvious behavioral facts an agent cannot infer from the empty schema.

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

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

Front-loaded with 'CALL THIS FIRST' and organized into bracketed clauses (Tier, When, Exempt). Every sentence carries information, though the run-on enumeration of ins and outs is slightly dense and could be split for readability.

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 fully explained, yet the description still covers what comes back and how the handle feeds other tools. For a zero-param entry-point tool, nothing an agent needs to call it correctly is missing.

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

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

Zero parameters, so baseline is 4. The description adds value by explaining the shape of the return payload (result.text and result.guidance_handle), which goes beyond the empty input schema.

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

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

States a specific verb+resource and its role ('Startup Guide + Handle'), immediately distinguishes it by naming the two things it returns (result.text brief and result.guidance_handle). An agent can tell it apart from siblings like discover_intent or workflow_advisor 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 triggering conditions: session start, after blocked_by=guidance_required, or when shared rules are unclear. It even lists the tools that are exempt, so the agent knows which calls do not require the handle. This is about as complete as routing guidance gets.

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

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

With no annotations, the description carries the full burden and largely does so: it discloses the return shape, the prerequisite, downstream call semantics (realign with moves), and constraints like 'do not invent shorthand' and 'ask which leaf if unclear'. It does not state read-only/idempotency explicitly, but the read framing is implicit throughout.

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 information-rich; the tier label and trigger condition are front-loaded, and each clause (prerequisite, return, next-step routing, aliasing warning) carries routing value. Some scenarios/Warnings could be tightened, but little is 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?

An output schema exists, so return values need not be fully specified, yet the description still names them. Combined with trigger conditions, prerequisites, and next-step guidance, it is nearly complete for a session-scoped selection reader; the only gap is the undocumented guidance_handle.

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

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

Schema coverage is 0%, so the description must compensate. It gives semantic meaning to map_session_id ('of the open MC') but never mentions guidance_handle at all, leaving one of two parameters undocumented anywhere. Partial compensation, hence a middling 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+resource ('read the latest committed MC session selection') and explicitly distinguishes it from siblings get_part_selection and request_part_selection. An agent can tell what this tool returns (part_layer + part_ids) 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 trigger conditions (Monica started selection from the legend finger icon, no prior request_part_selection in this turn), prerequisites (open MC's map_session_id), an alternative routing rule (prefer get_part_selection when you have selection_task_id), and even a negative instruction ('Do not resend the TS or request a new selection'). This is textbook when/when-not/alternatives coverage.

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

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

With no annotations, the description carries the full burden and largely delivers: idempotency per user_id, dual-surface rendering behavior (chat ui:// vs. browser tab for Cursor), and the guarantee that map_url is always returned. These are non-obvious operational traits an agent would otherwise guess wrong.

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

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

Front-loaded with the tier label and the primary action, then organized into When/Prerequisites/Next/Scenarios blocks. Dense but each clause carries operational meaning; slightly over-packed with jargon (I-1, MC-000, S004) that adds little for tool selection.

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 description covers workflow sequencing, the dual surface, and idempotency. Given 11 undocumented params, some input semantics remain thin, but an agent can call it correctly for the primary flows.

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 11 params, so the description must compensate. It explains new_project, presentation.view_name (with enum values), presentation.debug_panel, mode (as a driver of view defaults), and alludes to ts/ts_handle/job_id as inputs, but leaves expiry_seconds, guidance_handle, active_tal_id, interaction_flags, and user_id 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 (open/reuse the map visualization) and its position as the 'FIRST step of non-headless territory work'. It clearly delineates the two use cases (blank planning map vs. reuse an existing TS/job map), letting an agent distinguish it from siblings like ensure_map_viewer 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?

Explicit 'When:' clause names both entry conditions, gives the new_project=true vs. omitted behavior for reuse, and states prerequisites and the next step (hand user map_url, then ensure_map_viewer until viewer_status.connected). It also gives an explicit when-not: 'Do not open a second surface or call this tool again to fix a map.'

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

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

No annotations, so the description carries the full burden. It discloses poll semantics, the awaiting_user_selection → committed/expired/cancelled lifecycle, recommended_poll_delay_ms with fallback and a 250ms floor, and that the response carries do_this_next/poll_loop. It stops short of auth requirements or expiry timeout behavior, keeping it below a 5.

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

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

Front-loaded with the tier tag and When/Prerequisites/Poll-loop/Next structure, which is scannable. It is dense and somewhat long, but nearly every clause conveys actionable routing or loop behavior rather than 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 polling tool with an output schema (which owns return-value detail), the description covers trigger, prerequisite, loop timing, terminal states, and next steps. The only gap is the second parameter and expiry specifics, which are minor given the output schema.

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

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

Schema coverage is 0% across 2 params, so the description must compensate. It explains where selection_task_id comes from (request_part_selection or active_selection_task_id in map session state) but says nothing about guidance_handle, leaving half the parameters 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+resource — poll/retrieve committed part IDs — and frames it against the sibling that precedes it (request_part_selection) and an alternative (get_map_selection). An agent can distinguish this from request_part_selection and get_map_selection without opening schemas.

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

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

Explicit 'When' trigger, prerequisites (selection_task_id source, including the ezt://map-sessions state path), a concrete poll loop with status transitions, and a 'do not start a new selection' exclusion. It also names follow-on tools (realign, create_territory_from_parts, analyze).

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

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

With no annotations, the description carries the full burden and does so richly: it discloses the return shape (ts_handle + summary), the downstream contract, the error code for a failure mode, and the auth requirement (ezt_pat_ Bearer) for the Designer case. It even notes the absence of an MCP pull tool.

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

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

Front-loaded with purpose, return value, and next step before the edge cases, so an agent gets the essentials first. It is dense and long, but nearly every sentence carries actionable information rather than 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?

Complete for a multi-input import tool: input encodings, rejection rules, follow-on usage, and auth are all covered. The presence of an output schema is not relied upon since the description still clarifies the ts_handle handoff.

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 across 8 params, the description compensates substantially: geojson, geojson_text (sniffed gzip/zip), geojson_gzip (base64), part_layer, overlay_policy, point_layer, and tal_label are all explained. Only guidance_handle is left undocumented, so it is strong but not exhaustive.

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 (import) and resource (GeoJSON FeatureCollection), and immediately delineates the accepted input variants (standard points, export_geojson artifact, gzip/zip). It is clearly distinguishable from siblings like export_geojson.

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 to follow-on tools (get_map_visualization/analyze/export_geojson via ts_handle) and warns against reposting the GeoJSON body. It also states the exact rejection condition (TERRITORY_POLYGONS_WITHOUT_PART_IDS) and the workaround (part_layer + overlay_policy='centroid_within'), plus the Designer rolodex path.

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

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

With no annotations, the description carries full behavioral burden: geocoding, coordinate passthrough rules, unique id_field requirement, retention contract, async completion mandate, map_session_id binding, viewer_outcome semantics, and quota exhaustion 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?

Long but front-loaded with purpose and when-to-use guidance. Most sentences earn their place given the tool's complexity, though the dense block could be segmented for easier scanning.

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 25 params, async geocoding, and an output schema, the description covers prerequisites, failure modes, completion criteria, recovery paths, and map binding. It is complete enough for an agent to act without further guidance.

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 add meaning. It explains many complex params (id_field, latitude_field/longitude_field, force_regeocode, accept_suboptimal_geocodes, metric/workload/search/display/grouping fields, map_session_id, accounts_handle), but omits region_hint, country_hint, use_cache, min_confidence, point_layer, and label/label_field.

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: loading account/location rows or CSV point data into a TS point layer. Differentiates from siblings by naming auto_build/account_build and request_account_upload for large-file ingestion.

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 says ALWAYS before account-derived builds (auto_build, account_build), and for large files to call request_account_upload then this tool with accounts_handle. Also gives when to call tasks/cancel if coordinate passthrough counts look wrong.

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

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

With no annotations, the description carries full burden and delivers: it names concrete failure codes (ISOCHRONE_NOT_CONFIGURED, MIXED_BUDGET_TYPES, TOO_MANY_ORIGINS, TOO_MANY_BANDS, PROVIDER_QUOTA_EXCEEDED, BUDGET_OUT_OF_RANGE), quota semantics (fan-out claimed up-front, nothing spent on failure, cap raised by operator), async polling rules (follow _meta.next_action, use sleep_ms not estimated_remaining_ms), and partial-failure behavior (failed_requests[]). It also discloses non-obvious invariants: realign moves parts but never polygons, bands nest and overlap, part assignment is disjoint.

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 'When:' purpose, then organized into labeled blocks (ORIGINS x BANDS, QUOTA, LIMITS, GEOMETRY AND PARTS, Async, Then). Given the complexity it is mostly earned, but it is dense and long enough that some lines (e.g., repeated 'when/when-not' phrasing, scenario-code list) push past necessity.

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-shape explanation is not required, and the description instead supplies the missing operational context: prerequisite key, part_layer requirement, async task flow, error recovery path, and the downstream analyze call. For a high-complexity, high-cost batch fan-out tool, 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?

With 0% schema coverage across 14 params, the description must compensate and largely does: origins shape ({latitude, longitude, label?} or point-layer reference {point_layer, point_ids?, filter?, label_field?}), bands shape ([{time_budget_seconds}|{distance_budget_meters}] with same-unit rule), travel_mode allowed values, avoid value list, depart_at/arrive_at support, and numeric limits. It leaves tal_id, tal_label, traffic, route_type, part_overlay, map_session_id, and guidance_handle semantically unexplained, which is why it is not 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?

The description opens with a specific verb+resource: 'draw the area reachable by DRIVING from one or more origins within a time or distance budget', reinforced with concrete synonyms (service area, catchment, coverage ring, reachable range, isochrone, isodistance). It explicitly separates itself from siblings by stating it 'has no objective and does not balance workload' and contrasts with calculate_route and auto_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?

There is an explicit 'When:' clause with example phrasings, plus stated exclusions ('no walking or cycling reachable range, unlike calculate_route'; 'never feed it to auto_build'). Prerequisites (key, part_layer, ts_handle/map_session_id) and follow-up steps (analyze(...), realign) are laid out, so an agent knows exactly when to pick this over 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?

With no annotations, the description carries the full burden and delivers: 'Does not mutate TS', re-run analyze after any TAL/point change (I-2), dismiss=true hides the entire dock including header bar while keeping stats and sets analysis_panel.dismissed=true, and a thin {tal_analyses} object returns INVALID_REQUEST rather than an empty dock. These are real behavioral traits beyond any structured field.

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 a bracketed tier tag and 'When:' clause, then prerequisites and edge cases. Every sentence carries information, but the run-on packing of many clauses into single sentences makes it denser than ideal for scanning.

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

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

An output schema exists so return values need not be described, and the description still covers prerequisites, invalid inputs, dismiss lifecycle, dual-surface rendering, and re-run rules. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 0% across 9 params, so the description must compensate; it explains map_session_id, task_id/job_id, the required full-Analyze shape of analyses, the single|compare|executive|diagnostic values of presentation_mode (and that territory_metric_grid is not one of them), and dismiss. It leaves roles, labels, and guidance_handle unexplained, 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 names a specific verb+resource (show/load the Analyze JSON analysis panel into the MC bottom dock) and explicitly distinguishes itself from the sibling `analyze` tool by telling the agent to prefer `analyze(analysis_panel=single, ...)` when possible. An agent can identify this as the secondary display-only call 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?

It states exactly when to use it (after a completed analyze that omitted analysis_panel), the preferred alternative and its parameters, prerequisites (map_session_id plus a full Analyze result via task_id/job_id or analyses), and when NOT to pass analyses (dismiss call). Explicit exclusion and alternative routing are both present.

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

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

With no annotations, the description carries the full behavioral burden; it does disclose a key trait ('Returns part_id and attributes only; no geometry') and a prerequisite source. However, it says nothing about pagination behavior despite a page_token parameter, nor about auth, limits, or mutation risk (implicitly read-only but never stated).

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

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

Dense, labeled, and front-loaded with the When/Prerequisites/Next ordering; no wasted sentences. It reads like a compact routing card rather than prose, which is appropriate here.

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, and the routing context is solid. The remaining shortfall is the unexplained parameter set (notably the opaque guidance_handle and pagination via page_token), which leaves an agent guessing on invocation details.

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 6 parameters, so the description must compensate. It clarifies part_layer's origin and implies a filter capability, but leaves filter, part_ids, page_token (pagination!), max_results, and the opaque guidance_handle entirely undocumented, which is a substantial gap.

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

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

The '[Tier 2 — Part Metadata]' tag combined with 'enrich or filter parts before build, or inspect attributes without geometry' states a specific verb+resource and clarifies the scope is attributes, not geometry. It is distinguishable from build tools via the 'Next' routing, though it never names a direct alternative among the many selection/part siblings.

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

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

The explicit 'When:', 'Prerequisites:', and 'Next:' structure names the trigger conditions, the required part_layer source (ezt://part-layers), and the downstream tools (direct_build, configure_map). It clearly says when to use it but does not distinguish it from get_part_selection or request_part_selection, which sound closely related.

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

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

With no annotations, the description carries the full behavioral burden: it explains optimistic concurrency and STALE_TS_REVISION retry behavior, prohibits reposting the full TS or starting another selection, describes territory alias rules and failure handling, and requires asking the user when the destination is unclear.

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

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

The description is long but well-structured with When, Prerequisites, Next, Full atom, and Scenarios sections. It is front-loaded and every major sentence adds routing or operational value, though the density is high and some parameter handling is embedded rather than cleanly defined.

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, no-schema-description tool with no annotations and an output schema, the description is substantially complete on workflow, prerequisites, error handling, and alternatives. It remains incomplete on several obscure parameters, but an agent can likely invoke the core realign path correctly.

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

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

Schema description coverage is 0%, so the description must explain all 12 parameters. It gives strong semantics for map_session_id, ts_handle, ts, expected_revision, moves, and the to_territory_id concept, but leaves repair_policy, part_layer, guidance_handle, realign_operation, and remove_empty_territories unexplained. 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?

The description opens with a specific action and scope: move parts between leaf territories within ONE TAL. It clearly distinguishes this operation from structural siblings like territory_split/merge/rebalance and from visual selection via request_part_selection.

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

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

It explicitly states when to use the tool, required prerequisites, accepted TS reference parameters, when to fall back to get_map_selection, and when to avoid analyze. It also names the correct alternatives for structural and visual move scenarios.

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

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

With no annotations, the description carries full behavioral burden. It discloses useful traits: STALE_TS_REVISION on a moved master and a 'sequential merges only' concurrency constraint. However it doesn't state that this is a mutation, whether it's idempotent, or what permissions it requires, leaving real gaps.

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 'When:' and is compact, but the 'Tier 1 — Delegation Reintegrate' tag and trailing 'Scenarios: DL-003, DL-004, DL-006' are opaque tokens whose meaning an agent cannot act on without external references, adding noise rather than value.

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

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

For a complex 9-parameter mutation with an output schema (so returns need no explanation), it covers trigger, prerequisites, an error condition, sequencing, and follow-up. The gap is the unexplained optional parameters and the mutation/permission profile, which a no-annotation tool should disclose more of.

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 9 parameters, so the description must compensate. It names branch_metadata and expected_master_revision (both required) and hints at revision meaning via the STALE_TS_REVISION note, but master_ts, proposal_ts, all *_handle fields, map_session_id, and expected_master_content_hash are 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?

States a specific verb and resource: merge an approved proposal TS into master. This is clearly distinct from siblings like territory_merge or realign, and the 'approved proposal' qualifier scopes it. It doesn't explicitly name a competing sibling, so it stops short of a 5.

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

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

Gives an explicit trigger ('When: merge an approved proposal TS into master'), prerequisites, and a post-step ('Next: refresh master Analysis panel'). No explicit when-not or named alternative, but the context is clear enough for an agent to know when to invoke.

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

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

With no annotations, the description carries the full burden and does so richly: handle is single-use, claimed by the ingest job, and expires (default 1h); chunk-append semantics via upload_handle; coordinate passthrough behavior and suggested_ingest.args handling; and an explicit failure-recovery instruction (tasks/cancel on coordinate_passthrough_count=0 rather than waiting on national geocode). This is well beyond what annotations would normally supply.

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 a tier tag and the 'When' trigger, then proceeds through the staged-then-ingest flow and the four methods. It is long but dense with operative detail rather than filler; a few edge-case sentences (e.g. case-insensitive header passthrough) could be tightened, so not a perfect score.

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, zero-coverage staging tool with an output schema, this is unusually complete: it describes the return (suggested_ingest, upload_handle, geocode_plan fields), the handle lifecycle, and the downstream call contract. Nothing essential for correct invocation appears 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% across 6 params, so the description must compensate. It explains rows, csv_file, csv_text, and upload_handle clearly, plus implies TTL via 'expires (default 1h)'. However guidance_handle is never addressed and ttl_seconds is not named, leaving two params with no semantic grounding.

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 (stage account/location rows or CSV) and immediately frames the tool as a pre-step to ingest_accounts, which it explicitly names as the downstream sibling. An agent can distinguish it from ingest_accounts and request_assignment_upload without opening either schema.

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

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

Explicit 'When' condition (data too large to inline in a single ingest_accounts call), four enumerated staging methods with the conditions that select each (csv_file vs csv_text vs rows vs HTTP), plus the ordering constraint that ingest_accounts must run afterward. When-to-use and alternatives 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?

With no annotations, the description carries the full burden and does disclose meaningful traits: the handle is single-use, expires (default 1h), legacy columns auto-map, and each staging path returns upload_handle. It omits auth/permission requirements and size or validation limits, so it is strong but not exhaustive.

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 well-structured: the 'When:' condition is front-loaded, and the A/B/C/D enumeration makes the branching scannable. It is longer than most definitions but every clause carries actionable content; only the terse parentheticals border on clutter.

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

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

Given six parameters, zero schema coverage, and an existing output schema (so return values need no explanation), the description supplies the intake conditions, all staging paths, the auto-mapping behavior, the handle lifecycle, and the exact next call. An agent has everything needed to stage rows and proceed.

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 explain csv_file, csv_text (with the newline/JSON-encoding warning), assignments (appendable via upload_handle), and ttl_seconds indirectly via the 1h expiry note. guidance_handle is never mentioned, leaving one of six 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 (stage/upload) on a specific resource (part-to-territory assignment rows or a legacy spreadsheet) and explicitly names its role in a workflow. It clearly distinguishes itself from direct_build by framing itself as the staging step that feeds assignments_handle into direct_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?

Opens with an explicit 'When:' condition, names the alternative (inline in direct_build), enumerates four concrete staging methods (A csv_file, B csv_text, C assignments, D HTTP POST), and states the required follow-up call. Nothing about when to use it vs. alternatives 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?

With no annotations, the description carries the full burden and discharges much of it: it discloses the asynchronous task model, the commit poll loop with recommended_poll_delay_ms, the directive never to ask the human to type 'committed/done/go', the dual-surface behavior (Apps host vs map_url tab), and connection prerequisites. It stops short of describing failure/expiry behavior despite an expiry_seconds parameter, so not a full 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?

Well-labeled and front-loaded with When/Prerequisites/Poll loop/Next sections, and most sentences carry operational content. It is nonetheless dense and repeats the commit poll loop point ("The commit poll loop above is identical on both surfaces"), adding mild redundancy given the length.

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

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

For a complex async human-input tool with an output schema, the description covers the workflow, prerequisites, polling contract, and follow-on tools an agent needs to orchestrate correctly. The remaining gap is parameter-level guidance across the 12-argument schema, which is not addressed.

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 12 parameters, so the description must compensate and largely does not. It only indirectly touches part_layer, active_tal_id ("active TAL when realigning"), and realign_operation; it says nothing about prompt, purpose, expiry_seconds, guidance_handle, new_territory, destination_territory_id, remove_empty_territories, user_id, or ts.

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+resource – requesting human part selection on the map for realign, manual territory build, or return_list – and distinguishes this initiating tool from siblings like get_part_selection (polling) and get_map_selection (reading committed state). It is clearly not a tautology of the name, though the "[Tier 2 — Human Spatial Input]" prefix front-loads taxonomy rather than the plain purpose.

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

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

Explicit when-to-use (realign, manual territory build, return_list), prerequisites (MC-first, viewer connected, part_layer, active TAL when realigning), the user-initiated alternate path via the MC legend finger icon, and the follow-on tools (realign, create_territory_from_parts). It even names the alternative for reading an existing selection and says not to ask the human to re-select.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses the no-TAL/no-technician side effects, in-place replacement semantics for a repeated visit_layer_name vs. adding a second schedule, the UNDECLARED_FIELD failure mode, exclusion reporting (never silently dropped), and the post-submission sleep/poll/consume protocol. This is far beyond what a name and schema 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?

It is long and dense, but front-loads the tier label, trigger condition, and core behavior before drilling into parameter nuance and workflow handoff. Most sentences carry unique information, though the volume approaches manual territory and a few constraints 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?

An output schema exists, so return values needn't be described, and the description still fills the remaining gaps: prerequisites, error behavior, ambiguity resolution against calculate_route, and the do_this_next follow-up. For a complex 18-parameter scheduler, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 0% with 18 parameters, so the description must compensate, and it does for the critical ones: it explains ts/ts_handle omission, frequency_unit semantics (interval_days vs. visits_per_horizon), never_visit_values defaults, visit_layer_name behavior, and max_buckets_per_day. However, roughly half the parameters (horizon, objective, map_session_id, schedule_label, guidance_handle, emit_visit_layer, expected_revision, cadence_flexibility_pct) receive no explanation.

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

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

The description uses a specific verb+resource framing ('Expands demand across a repeating horizon and packs it into daily work clusters'), and even states the core decision explicitly ('This tool decides the day'). It distinguishes itself from siblings by naming auto_build, cluster_points, and calculate_route, and by clarifying 'It creates no TAL and assigns no technician.'

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

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

It gives an explicit trigger condition ('When: accounts carry a recurring cadence... and the user asks which day each visit happens'), names the neighbors, and even handles the ambiguity case ('When the user said route and a visit-frequency column exists, confirm they want a schedule, not calculate_route'). Prerequisites (ingest_accounts completed with cadence column declared) and follow-up routing are both 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?

With no annotations, the description carries the full behavioral burden and does so thoroughly: it discloses the no-overlap rule, error codes (SEED_PART_ASSIGNED, UNDECLARED_FIELD), async task_id flow with sleep_and_poll, handle-only result, target_status values, and scope behavior (ring-by-ring materialisation). This is far beyond what annotations would 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?

The description is long but well-structured with headers (TARGET, SCOPE, etc.) and front-loads the When-conditions and examples. Every section adds actionable detail, though some sentences (e.g., ring materialisation mechanics) could be trimmed without loss for an agent deciding to call the 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?

Given 15 parameters, nested objects, no annotations, and an output schema, the description is remarkably complete: it covers prerequisites, async handling, error cases, overlap constraints, result structure, and the follow-up analyze call. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 0%, so the description must explain all 15 parameters. It covers the critical ones—seed format, target types, tal_id behavior, part_filter/part_ids as allowlist, part_scope='explicit', point_layer, and map_session_id—but omits meaning for user_id, tal_label, ts_handle (as input), territory_name, and guidance_handle. Strong compensation overall, 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 gives a specific verb (grow) and resource (one territory from a seed) and explicitly distinguishes it from siblings by stating 'It does not partition, balance, or route.' An agent can immediately tell this apart from auto_build, direct_build, or territory_split without opening schemas.

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

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

It provides explicit 'When:' conditions with concrete examples, prerequisites (ingested point layer via ingest_accounts, part_layer, seed coordinates), and the alternative geocoding step. Exclusions are stated ('does not partition, balance, or route'), and it tells you to call once per seed for multiple franchisees.

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

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

With no annotations, the description carries the full burden and does disclose the key trait: the camera is session-only and does not write the TS, with configure_map named for persistence. It also states the prerequisite. It stops short of covering failure behavior, unspecified-field handling, or permissions, so it is strong but not exhaustive.

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 'When', prerequisite, and alternatives come in a logical order and each sentence routes the agent. Minor waste in the jargon header ('Tier 2 — Low-Level MC State') and the trailing 'Scenarios: residual backlog' line, which adds little.

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 7-parameter tool with only one required param and an output schema present, the description is nearly complete: it covers the primary mutable fields, the session-scoped semantics, and the alternatives. The only real gap is the undocumented guidance_handle, and return values need not be described given the output schema.

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

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

Schema coverage is 0%, so the description must compensate, and it adds genuine meaning beyond the schema: center is a [longitude, latitude] pair and zoom is bounded 0-24, neither of which the schema states. It covers mode, active TAL, pending job ref, center, zoom, and map_session_id, but leaves guidance_handle 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?

States a specific verb+resource (set MC map state) and enumerates exactly what it controls: MC mode, active TAL, pending job ref, and camera jump via center/zoom. It explicitly distinguishes itself from configure_map (durable persistence) and request_part_selection, so an agent can place it among siblings without opening schemas.

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

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

Provides an explicit 'When:' trigger list, a prerequisite (map_session_id), and two named alternatives with the condition that selects them ('Prefer configure_map for durable TS map_config', 'Prefer request_part_selection for selection workflows'). Routing guidance is unusually complete.

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

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

With no annotations, the description carries the full burden and delivers unusual depth: session durability when map_push_status=viewer_not_connected, status=already_on_map validated against the live render payload, status=refreshed with a map_refresh block and render_ack check, blocked_by=needs_route, non-destructive compose with a later ingest_accounts, and dual in-chat/map_url surfaces under the same session id.

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 structure is sensible — When, Prerequisites, dispatch behavior, then scenario tags — and the routing constraints are front-loaded. But it is a dense wall of near-run-on sentences with a lot of trailing edge-case detail (SSE paint, merge strategy, route recovery notes) that could be tightened considerably without losing meaning.

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 11-parameter, zero-required dispatch tool with no annotations, this is close to complete: prerequisites, dispatch rules, return fields (overlay_kind, overlay_id, viewer_hint, visibility block), failure/blocked states, and the dual-surface behavior are all covered. An output schema exists, so return-value explanation is bonus rather than obligation.

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 prose must compensate. It does explain ts_handle, inline ts, map_session_id (including why it is preferred for points), user_request, overlay_kind (enumerating part_layer/point_layer/tal/route), overlay_id, and route_id semantics. However merge_strategy, guidance_handle, expected_revision, and expected_content_hash are never mentioned, leaving roughly a third of the surface 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?

The description opens with a Tier-scoped statement of exactly what the tool does: resolve the four MC overlay families (part_layer, point_layer, tal, route) and dispatch to the correct underlying step. It differentiates from siblings by name — 'Prefer this over raw configure_map', 'use delete_route', 'calculate_route already draws its own result' — so an agent can route 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?

Explicit When clause with literal user phrasings, prerequisites (ts_handle from get_map_visualization, connected viewer), and conditions for calling configure_map first ('when the user already named a center and zoom') versus skipping it ('Skip that call when no center was named, and do not invent one'). It also states when NOT to use it for route deletion and route editing, naming the correct 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?

With no annotations, the description carries the full burden and does meaningful work: it discloses that context blocks (Territory Solution JSON, GeoJSON, account/CSV tables) are stripped, forbids secrets/PII, and states an acknowledgement is returned. It stops short of saying where feedback goes, whether it's durable or anonymous, or how acknowledgement affects subsequent calls.

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?

Five labelled fragments (When / Prerequisites / Next / Scenarios / content rules) are front-loaded and waste-free, with the triggering condition first. It is slightly telegraphic — 'Scenarios: GC-006' is opaque without external context.

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, and the when/prerequisites/next flow is fully covered. The material gap is the 15-parameter surface: with 0% schema description coverage, the description should carry parameter meaning but does not, leaving a substantial completeness hole.

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 15 parameters, and the description never maps its guidance to specific fields — it does not distinguish user_goal from what_happened, nor explain category/severity/confidence enums, include_context, related_tool, or correlation_id. The content restrictions loosely imply what belongs in free-text fields, but most parameters get no explanation in either the schema or the 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?

The bracketed tag names the tier and function ('Quality Feedback'), and the 'When' clause makes the resource (feedback submission about workflow/tool quality) unambiguous. It doesn't name a contrasting sibling, but the purpose is immediately intelligible without opening the schema.

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

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

Explicitly enumerates trigger conditions ('workflow blocked, partial, workaround required, confusing tool response, or missing capability/docs'), states 'Prerequisites: none', and specifies the follow-up ('Next: continue or end session after acknowledgement'). An agent knows exactly when to call this and what to do afterward.

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

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

With no annotations, the description carries the behavioral disclosure burden and does well: it states that cancellation is cooperative, that the task state may remain unchanged or become partial, and that the return shape matches the native method. It does not cover permission requirements or error behavior, so it falls short of full transparency.

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

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

The description is dense but front-loads the core purpose and usage rules, then adds prerequisite, return, and cancellation semantics. The internal tier and scenario labels add some noise, but the overall structure is efficient and appropriately sized for the 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?

For a one-parameter cancellation tool with no annotations and an existing output schema, the description covers purpose, usage conditions, prerequisite, return shape, and cooperative cancellation behavior. It is nearly complete, though it omits auth/error details that an agent might need 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%, so the description must add meaning for the sole task_id parameter. It does clarify that task_id comes from the immediately preceding async submission, which is useful, but it does not describe the ID format or any constraints beyond that origin.

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

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

The description identifies the tool as the tool-only equivalent of native tasks/cancel, which makes the cancel-task purpose clear from the name and text. It does not explicitly contrast with sibling tools such as tasks_get or tasks_result, but the operation is distinguishable from those by intent.

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

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

It gives explicit when-to-use guidance ('Use only when this mirror appears in tools/list'), names the alternative for Tasks-capable clients (native tasks/cancel), and states the prerequisite that task_id must come from the immediately preceding async submission. This leaves little ambiguity about selecting or invoking the tool.

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

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

With no annotations, the description carries the full burden and discharges it: it discloses that polling never starts work, that sleep_ms is the single authoritative sleep value, that estimated_remaining_ms must never be used as a sleep duration, that status=cancelled is a user stop not to be resubmitted, and that _meta carries queue_position/queue_depth/queue_lane/estimated_start_ms for explaining waits.

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 long, but the length is largely earned by the state-machine semantics (next_action vocabulary, queue metadata, anti-patterns) that an agent must follow. The mirror-vs-native constraint and prerequisite are front-loaded, though a couple of clauses (e.g., re-stating that next_action/sleep_ms are mirrored under _meta) are mildly redundant.

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 enumerated, and the description even confirms 'The result is the same Task status document returned by native tasks/get.' Combined with the routing rules, prerequisites, and discouraged behaviors, an agent has everything needed to invoke and sequence this tool 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?

One required param with 0% schema description coverage, so the description must compensate, and it does: 'Prerequisite: task_id from the immediately preceding async submission' tells the agent exactly where the identifier comes from. It stops short of format specifics (e.g., string shape/length), so not a full 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?

The description names a specific verb+resource (retrieve the Task status document for a submitted async task) and explicitly frames itself as the 'tool-only client equivalent of native tasks/get.' It distinguishes itself from siblings tasks_result and tasks_cancel, telling the agent it is the polling/status read, not the result fetch or cancel.

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

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

It states when to use it ('Use only when this mirror appears in tools/list'), when not to (Tasks-capable clients use tasks/get), the prerequisite (task_id from the immediately preceding async submission), and routes each next_action value to the correct follow-up call (sleep_and_poll, consume_result, stop_error). Exclusions and alternatives are explicit.

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

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

With no annotations, the description carries the full burden and does well: it discloses the prerequisite, the exactly-once/idempotency expectation, that the result is handle-only (never inline TS when a handle exists), and the no-polling constraint. It stops short of stating what happens if called before completion or whether repeated calls error, which a mutation-adjacent consume step would benefit from.

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 tier/mirror identity and the trigger condition, then layers prerequisite, return shape, and follow-up routing. Dense and jargon-heavy ('ts_handle', '_meta.next_action') but every sentence carries operational information; nothing is redundant.

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 fully spelled out, yet the description still characterizes the return as the originating tool's terminal handle-only result. Combined with the workflow preconditions and post-conditions, an agent has everything needed to invoke it correctly at the right moment.

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

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

Schema description coverage is 0%, so the description must compensate for the single task_id parameter, and it does: it specifies the value is the task_id from the completed Task returned by tasks_get, and an alternative reuse of the same task_id as job_id. It does not state behavior for an invalid or incomplete task_id.

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 — retrieving the terminal result of a completed Task — and explicitly frames it as the tool-only mirror of native tasks/result. It is clearly distinguishable from siblings tasks_get (which produces the status this tool consumes) and tasks_cancel.

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 precise invocation conditions: call exactly once after tasks_get returns status=completed and _meta.next_action=consume_result, and do not poll while working. It also routes follow-up work (pass ts_handle or task_id as job_id to analyze with explicit tal_ids) and forbids the wrong recovery path (never resubmit a build on an Analyze lookup error).

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