SeatLayer

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description adds genuinely useful context beyond them: the auth prerequisite ('Needs a connection allowed to publish') and the blast-radius clarification ('Events keep their version'). It does not explain why the operation is destructive (what exactly it overwrites), which keeps it short of a 5 given the destructive flag.

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

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

Front-loads the purpose, then layers Use when / Not for / Next / Example in a scannable structure. Every sentence carries a distinct piece of information with no redundancy.

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

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

For an activation/mutation tool with no output schema, the description supplies purpose, prerequisites, alternative, follow-up action, and a concrete invocation example. An agent has everything needed to call it correctly and to route elsewhere if appropriate.

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

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

Schema description coverage is 100%, so all three parameters are already documented with their sources (list_event_configurations, get_event_configuration revisions). The example reinforces the format with concrete values but adds little beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb and resource ('Make a published version the default') and immediately clarifies a subtle scope ('Events keep their version'). It distinguishes itself from the closest sibling by pointing to rollback_event_configuration as the opposite operation.

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

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

Explicit 'Use when' (a newer version should be used from now on) and 'Not for' (going back → rollback_event_configuration), plus a 'Next' step pointing at plan_inventory_change set_configuration_binding. All three when/when-not/alternative dimensions are 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?

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description needn't restate it. The description adds useful domain semantics — the object is non-sellable and dimensioned in metres — but says nothing about the optimistic-concurrency role of expectedUpdatedAt, what happens on a stale value, or the effect on the existing chart layout.

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

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

Four short blocks — definition, use-when, not-for, example — with the purpose front-loaded and zero filler. The negative guidance and the example each earn their space by preventing a specific mis-call.

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-parameter creation tool with no output schema, the description covers purpose, alternatives and a call example, and annotations cover safety. It stops short of explaining the concurrency contract around expectedUpdatedAt and when to prefer nearObjectId over placement, which are the main remaining decisions an agent must make.

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

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

Schema description coverage is 100%, so every parameter is already documented, including defaults for fill, side, shape, floorId and placement and the meaning of nearObjectId. The worked example shows a realistic minimal call, but it only echoes schema fields rather than adding new semantics (e.g. placement vs nearObjectId precedence is left to the schema).

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

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

States a specific verb+resource ('Add a named area that is not sold') and immediately constrains it with concrete examples (dance floor, registration desk, lobby, photo booth) plus units (metres). It is clearly separable from add_ga_area and add_landmark, which occupy adjacent object kinds.

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

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

Explicit 'Use when' condition ('the venue needs a space marked on the map that nobody buys') and explicit 'Not for' exclusions naming the correct alternatives for sold standing areas and for landmarks. An agent can route between the three sibling tools without opening any schema.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent, closed-world write, so the safety profile is covered. The description adds the optimistic-concurrency token via the expectedUpdatedAt example but never explains what happens on a version mismatch, nor whether the new booths collide with or displace existing objects. Useful but not rich behavioral context.

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

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

Three short labeled lines, front-loaded with the action and immediately followed by when/when-not and a concrete call shape. No sentence is wasted and an agent can parse it at a glance.

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

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

With 6 parameters at full schema coverage and annotations present, the definition is largely self-sufficient. The remaining gap is that no output schema exists and the description never states what a successful call returns (booth count/ids) or how to recover from an expectedUpdatedAt conflict.

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

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

Schema description coverage is 100% and every parameter is documented in-schema (ranges, defaults, enum for placement, sourcing of categoryKey/expectedUpdatedAt), so the baseline of 3 applies. The example payload adds only marginal value — it confirms the categoryKey string format and the ms-epoch shape of expectedUpdatedAt, but says nothing about floorId or placement.

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 ('Add a grid of expo or market booths') plus a scope constraint ('beside the layout'), which is more than the title restated. It separates itself from the mutation sibling update_booths, but does not distinguish itself from the very similar array-creation siblings add_table_array / add_row_block / add_area.

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

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

Explicit 'Use when' trigger ('4 rows of 10 booths') and an explicit 'Not for' with a named alternative (update_booths). The exclusion is narrow, though: it does not say when to prefer add_table_array or add_row_block instead, which is the more likely selection error for a grid-creation tool.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds real value beyond them by disclosing placement behavior (rows start beyond existing seats) and, via the example, the expectedUpdatedAt concurrency token. It stops short of stating what happens on a stale token or what the response contains, so not a 5.

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

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

Three tight blocks — behavior, when/when-not, example — front-loaded with the action and no filler. Each sentence carries distinct 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?

For a 9-parameter mutation tool with no output schema and full schema coverage, the definition covers purpose, routing, and a worked example. It could say more about return values or concurrency failure, but an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so every parameter including defaults and ranges is already documented. The example illustrates a realistic combination (rowCount 12, spreadDegrees 110, aisles two) but adds no format or constraint detail the schema lacks; baseline 3 applies.

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

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

Specific verb+resource ("Add rows that curve around the stage") with a concrete domain frame (theatre, amphitheatre, lecture hall) and scope constraint ("starting beyond any seats already there"). It is unambiguously distinguishable from add_row_block and build_semantic_venue, which it names.

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

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

Explicit when-to-use triggers are given with sample utterances ("12 curved rows facing the stage", "semicircle of seating", "270-degree bowl"), plus a "Not for:" line that routes to add_row_block for straight rows and build_semantic_venue for a whole venue. Nothing is left to inference.

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

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

Annotations already declare it is a non-read-only, non-destructive, non-idempotent, closed-world mutation, so the safety profile is carried. The description adds the placement semantics ("beside the layout") and a concrete payload showing expectedUpdatedAt as a concurrency token, but never states what happens on a stale token or that repeated calls create duplicate areas despite idempotentHint=false.

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

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

Three short lines plus one example, with the core action front-loaded and the exclusion placed before the payload. No sentence is filler.

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

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

For a 7-parameter mutation with full schema coverage and annotations, the description covers purpose, routing to the sibling updater, and a usable example. It lacks only the optimistic-concurrency failure behavior for expectedUpdatedAt and any hint of what the call returns, which matters somewhat given there is no output schema.

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

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

Schema description coverage is 100%, so the schema already documents every field including defaults for label, floorId and placement. The worked example usefully shows how placement "front" and categoryKey combine for the pit scenario, but it does not explain the required expectedUpdatedAt round-trip beyond showing a number.

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: adding a standing (general admission) area with a fixed capacity, positioned beside the layout. That wording separates it from the generic add_area and from update_ga_areas without requiring the schema to be opened.

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

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

Explicitly names the trigger case ("a 500-person pit in front") and an explicit exclusion with the correct alternative ("Not for: changing one (use update_ga_areas)"). Both when-to-use and when-not-to-use are 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?

Annotations already declare it is a non-read-only, non-destructive, non-idempotent mutation, so the safety profile is covered. The description adds value beyond that with the mutually-exclusive role/icon rule and a concurrency token (expectedUpdatedAt from get_chart), which implies stale-write protection. It does not say what is returned or how placement defaults resolve, keeping it at 4 rather than 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 resource list, then when-to-use, exclusions, and an example — a sensible agent-first ordering with no filler sentences. The long enumeration of landmark types is redundant with the role enum and is the only thing keeping it from a 5.

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?

Nine parameters, five enums, no output schema and no annotation coverage of results. The description never says what comes back (e.g. created object ids) or how a created landmark can subsequently be found or updated, which matters for a mutation whose follow-up calls (get_chart, update_shapes) need identity. Adequate but with a real gap for a 9-param tool.

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

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

Schema coverage is 100% and every param carries an enum and inline description, so the baseline is 3. The description goes slightly further by stating the role-vs-icon exclusivity and by including a worked example that shows how role, label, placement and expectedUpdatedAt combine — a real usage detail the schema cannot express.

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 (add) and a precisely enumerated resource (venue landmarks: bar, entrance, exit, screen, sound desk…) plus a second class of wayfinding icons. It closes with a contrast against the two most confusable siblings, add_area and add_text, so the agent can separate 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?

Explicit 'Use when' block gives three natural-language buyer phrasings that trigger this tool, and 'Not for' names the alternatives (add_area for named floor areas, add_text for plain text) with the distinguishing condition. The constraint 'Pass role or icon, not both' is also a usage rule.

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

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

Annotations already declare it is a non-readonly, non-idempotent, non-destructive closed-world mutation, so the safety profile is covered. The description adds that the block is placed 'beside the current layout' (additive, not replacing) and that sectionLabel wraps it in a new section, but it never explains the required expectedUpdatedAt concurrency check, what happens on a stale timestamp, or whether the addition is atomic.

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

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

Four compact lines: what it does, when to use, when not to use, and a concrete example. The core statement is front-loaded and every line carries distinct information with no restatement of the title.

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

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

For a 10-parameter mutation with full schema coverage, no output schema, and complete annotations, the description covers purpose, routing, and a usage example, which is nearly everything an agent needs. The gap is the optimistic-concurrency contract implied by the required expectedUpdatedAt and the behavior on conflict.

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

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

Schema description coverage is 100%, so parameter meaning is already carried by the schema and a baseline of 3 applies. The description adds value only through a worked example that shows a coherent parameter set in situ; it does not explain semantics beyond the schema (e.g. how blockStyle 'intertwined' interacts with curveStyle, or what floorId defaults to in practice).

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 (add a block of seated rows beside the current layout) plus the optional section-creation behavior, which is not obvious from the name alone. It explicitly names the two nearest alternative tools (build_semantic_venue, fill_section_with_rows), so an agent can separate it from the crowded seating-creation sibling set.

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

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

Contains an explicit 'Use when' trigger phrase with a natural-language example ('add 10 rows of 20 at the back') and an explicit 'Not for' clause routing to two named alternatives. When-to-use, when-not-to-use, and alternatives are all present.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=false, openWorld=false, so the safety profile is covered. The description adds genuinely non-structured behavior: the first stage on a floor defines seat orientation, which an agent must know before placing multiple stages. It does not discuss optimistic-concurrency failure behavior for expectedUpdatedAt, which is the one remaining behavioral 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?

Four short, labeled lines: identification, use-when, not-for, example. The differentiating fact (floor-defining stage) is front-loaded and there is no restatement of the title or schema.

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

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

For a nine-parameter mutating tool with no output schema, the description covers purpose, entry conditions, exclusions and a worked example. What is missing is small but real: what happens when expectedUpdatedAt is stale, and whether the call errors or otherwise fails, which matters for a write tool the agent may retry.

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

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

Schema description coverage is 100%, and all nine parameters carry their own defaults, enums and constraints (side, placement, nearObjectId, expectedUpdatedAt). The description's example payload reuses values already present in the schema enums, so it demonstrates composition but adds no new parameter semantics. Baseline 3 applies when the schema does the heavy lifting.

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 ('Add a stage or playing surface') and enumerates the concrete variants (pitch, court, rink, ring). It goes on to describe the semantic role of the object ('the first stage on a floor becomes what every seat faces'), which lets an agent distinguish add_stage from shape-editing siblings 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 'Use when' clause (no stage exists, a second one is needed, or a sports surface is required) and an explicit 'Not for' clause that names the two alternative tools: update_stage_kinds for shape changes and update_shapes for name/colour. This is the full when/when-not/alternative triad.

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

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

Annotations already establish that this is a non-destructive mutation, not idempotent, and closed-world. The description adds useful behavior: SeatLayer actively computes a path through obstacles, and lineId changes the mode from drawing a new route to converting an existing line. It does not discuss permissions, failure modes, or what data is overwritten when reusing expectedUpdatedAt, so a 4 rather than 5.

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

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

The description is front-loaded with the core action, followed by usage guidance, exclusions, next step, and an example. Every sentence carries actionable information with 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 non-destructive mutation with full schema descriptions, no output schema, and clear annotations, the description covers what the tool does, its two modes, when to use it, when not to, and the follow-up rendering step. Nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real semantic value by explaining the mutually exclusive modes: fromGateId/toSectionId draws a new route, while lineId converts an existing line. The example also clarifies the expectedUpdatedAt concurrency token in context.

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

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

The description states a specific verb and resource: drawing a step-free route from a gate to a section, or marking an existing line as step-free via lineId. It names and distinguishes relevant siblings (place_gate and update_gate) and explains what routing considerations SeatLayer handles.

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 'Use when' example, a 'Not for' exclusion pointing to place_gate and update_gate, and a 'Next' step to render_preview. An agent knows both when to call this and what to do afterwards.

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

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

Annotations already declare the safety profile (readOnly=false, destructive=false, idempotent=false, closed-world), so the description only needs to add context. It adds that objects are appended 'beside the layout' rather than replacing it, and the example payload surfaces expectedUpdatedAt, but it never states what happens on a stale concurrency token or that non-idempotent repeat calls stack duplicate grids.

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

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

Three short, front-loaded lines: what it does, when to use it, when not to, then a concrete example. No sentence is redundant and the exclusion is not buried.

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

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

For an 8-parameter mutation with no output schema but full annotation coverage, the description gives purpose, trigger, alternative and a worked payload, which is enough to call it correctly. Remaining gaps are secondary behaviors (conflict handling, whether chairs count is derived, floor/placement defaults), all of which the schema covers separately.

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

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

Schema coverage is 100%, so parameter documentation is already carried by the schema and the baseline is 3. The example goes slightly beyond it by showing how tableRows, tableColumns, seatsPerTable and categoryKey compose into a single grid request, clarifying the intended interpretation of the row/column pair.

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 ('Add a grid of round or rectangular tables with chairs') and scopes it to placement beside the existing layout. It explicitly distinguishes itself from the layout-building sibling build_semantic_venue, so an agent can pick it without reading either schema.

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

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

Provides an explicit 'Use when' pattern with a natural-language example ('3 rows of 5 tables of 10') and an explicit 'Not for' exclusion naming the alternative tool. Both the positive trigger and the routing rule are stated, 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?

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the safety profile and the 'creates a new object rather than modifying' behavior are largely covered structurally. The description adds useful context about visibility semantics (showAt 'when buyers see it') and placement relative to another object, but says nothing about what happens on repeat calls (non-idempotent duplication) or what identifier is returned, which matter for a 10-parameter mutation.

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

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

Front-loaded purpose sentence, then labeled 'Use when', 'Not for' and 'Example' blocks. Every line carries distinct routing or parameter information; nothing is redundant with structured fields.

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-parameter creation tool with full schema coverage and no output schema, the description covers purpose, routing, and a realistic invocation. The main remaining gap is the absence of any statement about the return value (e.g. the new text id) and duplicate-text behavior, which an agent cannot recover from structured fields here.

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

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

Schema coverage is 100%, so baseline is 3, but the worked example goes beyond the schema by showing a coherent combination of six parameters in context — notably the interplay between nearObjectId and side, which the schema only implies ('Ignored with nearObjectId' on placement). That cross-parameter insight is genuine added value.

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

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

States a concrete verb and resource ('Add a text label to the map') and illustrates it with domain-specific examples like 'Gate C' and 'Step-free route'. The 'Not for' clause distinguishes it from update_texts and the update_* family, so an agent can route correctly without opening schemas.

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

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

Explicit 'Use when' condition (user wants words no section/row/landmark name already shows) plus a 'Not for' clause naming three concrete alternatives (update_sections, update_rows, update_shapes) and update_texts for editing. Both the positive and negative decision boundaries are 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?

The annotations already establish that this is a non-read-only, non-destructive, non-idempotent mutation. The description adds useful behavioral context by stating that it saves a new draft and creates no seats. It could say more about concurrency or stale-revision behavior, but with annotations covering the safety profile this is a solid disclosure.

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

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

The description is front-loaded with the action and its side effects, followed by a clear usage condition, the next step, and an example. Every sentence contributes directly to selecting and invoking 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 nested-parameter mutation with no output schema, the description gives enough to understand when to call it, what it changes, and what to do next. It does not describe the response shape, but the workflow guidance and example compensate for most of that gap.

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

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

Schema description coverage is 100%, so the schema already carries the parameter documentation burden. The description adds a concrete example payload that shows how assetId, expectedDraftRevision, expectedUpdatedAt, and nested categoryAnswers are used together. That is valuable but not a substitute for deeper semantic 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 states a specific action and resource: recording the user's answers to the plan's open questions. It also distinguishes the tool from its siblings by naming list_reference_capacity_questions as the prerequisite and render_reference_capacity_preview as the next step.

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 says when to use the tool: after the user has answered list_reference_capacity_questions. It also tells the agent what to do next, which is render_reference_capacity_preview, leaving little ambiguity about sequencing.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real operational detail: plan expiry after 15 minutes, that seats changed since planning are silently left alone while anything else changed causes a refusal requiring a re-plan, and that replaying the same planId returns the first result. These are exactly the failure modes an agent needs to anticipate.

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

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

Front-loaded with the core action and the usage gate, then compressed into semicolon-separated clauses; nothing is padding. The permission sentence is dense, and the trailing clause 'a map change publishing' is truncated enough to be slightly ambiguous, slightly reducing 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?

With only two required parameters, no output schema, and annotations covering the safety profile, the description still covers permissions, expiry, staleness/refusal behavior, idempotency, and the next tool to call. Nothing material an agent needs to invoke 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 100%, so both parameters are already documented. The description still adds intent-level meaning: planId must be the exact token from plan_inventory_change, and confirm must be sent only after human approval in chat — plus a concrete example value showing the plan token shape.

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 — apply the change described by a plan_inventory_change plan — and explicitly ties itself to that sibling as the plan producer, so an agent can tell it apart from plan_inventory_change and from the many other mutation 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?

The 'Use when:' clause gives an explicit gate (only after the person said yes in chat to that plan's summary) and encodes the companion tool chain: plan comes from plan_inventory_change, follow-up is get_event_sections. It also names required permissions per change type, which further scopes when the call can succeed.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is known. The description adds useful workflow context (a human confirmation gate, the meaning of assumptionsConfirmed as acceptance of SeatLayer's inferred rows), but never says whether existing seats are replaced, what happens on a non-matching expectedUpdatedAt, or how to recover.

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

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

Purpose and use condition are front-loaded in the first two sentences; the example is long but earns its place by demonstrating the required-parameter shapes. Minimal 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 16-parameter destructive mutation with nested objects and no output schema, the description covers the required core and the confirmation gate but leaves the optional plan-mirroring parameters (numberingPolicy, standingSections, categoryOverrides, nonSellableSections) defined only by reference to another tool, and says nothing about the operation's effect on existing inventory.

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

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

Schema coverage is 100%, so baseline is 3, but the worked example adds real value by showing a complete valid call and disambiguating free-text fields like sourceDescription ("Owner in chat") and the aggregateEvidence enum choice. It does not clarify the ten optional params that the schema only describes as "As in plan_reference_capacity."

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

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

States a specific verb and resource: "Create the seats from the seat-count plan," and enumerates the outputs (rows, numbers, categories, accessible seats). It implicitly distinguishes itself from the planning/preview siblings by requiring the plan to already exist, though it never names them directly.

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

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

"Use when: the user saw the preview and confirmed" gives a concrete precondition tying this to the preview/render step. It does not name an alternative tool explicitly (e.g., plan_reference_capacity, apply_reference_inventory) or state when not to use it.

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

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

Annotations already declare this as destructive, non-read-only, and non-idempotent. The description adds valuable behavioral context beyond that: it replaces only seats it previously created and is refused if they do not fit. It still does not describe authentication needs or the success response, so it is strong but not fully complete.

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

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

The description is front-loaded with purpose, then 'Use when', then 'Not for', then an example. Every part earns its place, including the example, which is justified by the complex nested schema.

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

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

The description gives the key workflow prerequisite, exclusion, and mutation constraint, while the schema covers all 7 parameters in detail. The main remaining gap is that, with no output schema, it does not state what a successful response contains or what the caller should expect afterward.

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

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

Schema description coverage is 100%, so the schema carries the parameter documentation burden. The description still adds useful semantics by mapping sections to rows/tables/booths/standing and providing a concrete example that shows how categories, sections, assetId, evidence, and expectedUpdatedAt fit together.

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 specific verb and resource: filling traced sections with known rows, tables, booths, or standing areas, including categories. It is distinguishable from sibling tools like plan_reference_capacity and compile_reference_skeleton because it is clearly the application step with per-section counts.

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

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

The description explicitly says when to use it ('after compile_reference_skeleton, with counts per section known') and when not to use it ('only a total known' → use plan_reference_capacity). This gives an agent both the precondition and the alternative routing decision.

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

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

Annotations already flag a destructive, non-read-only, idempotent write, and the description adds genuinely behavioral context they lack: omitting confirmApply downgrades the call to a preview. That preview/save distinction is exactly what an agent needs before invoking a destructive tool, though what existing restriction state gets overwritten is still unstated.

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 effect and trigger come first, the preview caveat second, and the example last as supporting detail. The example is somewhat verbose but earns its place by showing a well-formed confirmApply payload.

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 destructive mutation with no output schema, the description covers the key decision (preview vs. save) and the source of the seat ids. It leaves unaddressed what happens to seats previously marked restricted and whether the change can be undone, but annotations carry the destructive profile.

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

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

Schema description coverage is 100%, so every parameter including expectedUpdatedAt and includeSeatChairs is already documented. The example illustrates confirmApply and the required identifiers in use, but adds little semantic meaning beyond the schema text and explains nothing about the optimistic-concurrency role of expectedUpdatedAt.

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 effect: marking the seats that score_sightlines flagged as "restricted view" for buyers, which cleanly separates it from the scoring sibling. The phrasing 'Mark seats score_sightlines flags' is slightly garbled, but the intent and resource are unmistakable.

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

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

'Use when: the user accepts the result' gives an explicit trigger condition, and it makes clear this is the downstream step after score_sightlines. It does not name any alternative or exclusion, so it falls short of the top band.

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

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

Adds context beyond the annotations: the operation requires a publish-capable connection, is gated on confirmApprove: true, and is blocked for retracted records. That complements idempotentHint=true without restating it. It does not say what happens to an already-approved record or what the response returns.

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

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

Front-loaded with the action and effect, then trigger, constraint, and next step. The example earns its space by showing a concrete valid payload, though it is the longest element in an otherwise tight description.

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

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

Covers what matters for a 9-parameter mutation tool with no output schema: auth requirement, approval gate, state exclusion, and the next step in the workflow. Optimistic concurrency via expectedUpdatedAt is explained by the schema, not by the description, which is the only real gap.

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

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

Schema coverage is 100%, so every parameter already carries its own description and the baseline is 3. The description only adds meaning for confirmApprove, which the schema already states must be true. The example confirms a valid combination of scope/objectId/approvedByRole/expectedUpdatedAt but adds little extra semantics.

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

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

States a specific verb and resource: approve a draft Verified View record, plus the downstream effect (buyers see it after publishing). That phrasing separates it from approve_event_configuration and approve_reference_blueprint, which share the 'approve' verb but act on different objects.

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 ('Use when: the user reviewed it') and a follow-up step ('Next: prepare_chart_review'). It also fences in the guard conditions (confirmApprove required, retracted records ineligible). It does not name the inverse sibling (retract_confidence_evidence), so routing away from this tool is only implied.

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

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

Annotations already declare non-read-only, idempotent, non-destructive, closed-world behavior, so the description's added value is the permission prerequisite and the review→approved state transition leading to publish. It does not mention failure modes for a stale expectedRevision or the existence of rollback_event_configuration, which would complete the mutation story.

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

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

Three short lines plus an example, front-loaded with the action, then the condition, then the next step. Nothing is wasted and each line 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?

No output schema exists, so the description must carry the workflow, and it does: prerequisite, trigger, and successor tool. It falls short of a 5 by not indicating what a successful approval returns or how to recover from a revision conflict.

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

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

Schema coverage is 100%, so a baseline of 3 applies, but the worked example payload makes the shape concrete and shows the ID format (ec_...) plus how version and expectedRevision differ in practice. It still leaves the optimistic-concurrency meaning of expectedRevision implicit.

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

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

States a specific verb and resource ('Approve a configuration version in review'), including the precondition state of the resource. It is clearly separable from the sibling publish_event_configuration, which it names as the following step.

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

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

'Use when: the user agrees the setup is right' gives an explicit trigger condition, and 'Next: publish_event_configuration' names the follow-up tool. The prerequisite 'Needs a connection allowed to publish' rules out calls the agent cannot make.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent mutation. The description adds useful preconditions—all sections, zones and stages confirmed and named, no blockers, user agreement—but does not explain what approval changes, how failures are reported, or how the expected revision protects concurrency.

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

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

The description is compact and front-loaded: purpose first, then when to use, next step, and a concrete example. Every line contributes useful selection or invocation context without 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 two-parameter approval action, the description covers purpose, prerequisites, usage condition and the follow-up tool. It lacks return-value and failure-mode detail, which is relevant because no output schema is provided, but the core invocation context 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 100%, and both parameters are fully described in the schema itself, including where assetId and expectedBlueprintRevision come from. The description's example repeats the parameter shape but does not add semantic detail beyond the schema.

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

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

The description states a specific verb and resource: 'Approve the proposed outline.' It adds the key precondition that every section, zone and stage must be confirmed and named. It is clear, though it refers to the resource as 'outline' rather than consistently as 'blueprint,' and does not directly distinguish itself from propose_reference_blueprint.

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

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

It gives a clear usage condition: use when get_reference_blueprint shows no blockers and the user agrees. It also names the next tool, compile_reference_skeleton. It does not explicitly state when not to use it or name alternatives such as propose_reference_blueprint.

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

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

Goes beyond annotations by disclosing the atomicity guarantee ('Saves nothing if a fix would add a new error') and the return shape (score before and after), which the agent can't get from the schema since no output schema exists. Annotations already flag destructiveHint=true and idempotentHint=false, so the description's job is to reassure about blast radius, which it does by scoping the fixes as safe and the operation as all-or-nothing; it could still say more about what happens to non-matching issues.

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

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

Front-loaded purpose sentence, then labelled Use when / Not for / Example sections. Every sentence earns its place, including the failure clause which prevents an agent from assuming a partial save.

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

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

Covers scope of fixes, prerequisites (a prior validate_current_chart run), exclusions with sibling tools, failure semantics, and return values. For a one-parameter mutation tool with no output schema, nothing material 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 100% and the single expectedUpdatedAt parameter is fully documented in the schema, so the description's example {"expectedUpdatedAt": 1790000000000} only illustrates the shape rather than adding meaning. Baseline 3 is appropriate when the schema carries the semantics.

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

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

States a specific verb (apply) and resource (automatic fixes) and enumerates the exact fix classes: seat spacing, unreadable label/text colours, text placement, and a shared category split into two at the same price. It also anchors itself to validate_current_chart's findings, making it easy to distinguish from siblings like update_sections or reset_seats.

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

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

Explicit 'Use when' condition (validate_current_chart reports errors/warnings these fixes cover) and an explicit 'Not for' clause that routes the agent elsewhere for section moves and category colour changes, naming update_sections and update_chart_categories. Nothing is left to inference about when to pick this tool versus alternatives.

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

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

Annotations already declare destructiveHint=false and openWorldHint=false, so the bar is lower, and the description adds real value: the tool returns exactly two images, must be called once per session, and its answer dictates fallback behavior. It does not explain why readOnlyHint=false (presumably per-session probe state), leaving a small gap between the 'returns pictures' framing and the non-read-only annotation — but this is a tension, not a contradiction.

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

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

Four short, front-loaded lines covering purpose, timing, follow-up, and fallback with zero filler. The phrase 'Its answer says what to do' is slightly cryptic about what the answer actually contains, a minor economy-driven ambiguity.

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

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

With no output schema and no parameters, the description carries the load well: it tells the agent the return is two pictures and that the response text may redirect it. It could be clearer about what a non-picture answer implies, but an agent has everything needed to call and interpret the result.

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

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

The tool takes zero parameters, so the baseline is 4; the description correctly signals this with the 'Example: {}' invocation, confirming there is nothing to supply. No additional parameter meaning is needed or possible.

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

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

States a specific verb and resource — returns two test pictures to verify image reading on the connection — and explicitly differentiates itself from the sibling confirm_vision_probe, which handles the follow-up step. An agent can distinguish the two 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 concrete when-to-use guidance ('once per session, before picture tools'), names the required next step ('confirm_vision_probe with what you read'), and even handles the negative path ('No pictures? Its answer says what to do'). This is explicit routing, not implied usage.

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

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

Annotations already declare destructive=true and non-idempotent, but the description adds the concrete consequence ('it replaces the draft') and describes the dry-run path ('checkOnly true lists every problem by field without saving'). It doesn't cover failure modes on the save path or the role of expectedUpdatedAt as a concurrency guard, so it stops short of fully rich.

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

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

Front-loaded with the action, then crisp labeled sections (Use when / Not for / Format / Example). The example is long but is the payload contract for a nested free-form object, so it earns its space.

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

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

For a destructive, nested-payload, no-output-schema tool, the description supplies the destruction warning, dry-run mode, format pointer and a concrete example. The spec object allows additionalProperties with no enumerated field list, so full coverage rests on get_venue_spec_format rather than this description.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: checkOnly is characterized as a per-field problem listing, and the example shows spec shape and the expectedUpdatedAt value in situ. It doesn't explain what expectedUpdatedAt guards against, keeping it below 5.

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

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

States a specific verb and resource ('Build a whole chart in one call from a Venue Spec') and enumerates exactly what the spec covers: categories, prices, stage, rows, tables, standing, booths and landmarks. This clearly separates it from siblings like build_simple_chart, build_semantic_venue and the granular add_* 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?

Explicit routing: 'Use when: the user describes a new venue', 'Not for: a chart to keep (it replaces the draft) or small edits', and a pointer to get_venue_spec_format for the input format. When-to-use, when-not, and the alternative are all 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?

Annotations already flag destructiveHint=true and idempotentHint=false, and the description reinforces this with the concrete blast radius ('it replaces everything') plus a non-obvious behavior rule: 'Each layout takes only its own counts.' It also prescribes the post-call workflow, which annotations cannot express.

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

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

Front-loaded purpose sentence, then labeled Use when / Not for / Next / Example blocks with zero filler. The example is compact and demonstrates cross-parameter composition that prose would take longer to convey.

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 24-parameter destructive builder with no output schema, the description covers selection, destruction scope, and the next steps well. The one gap is what the call returns (a rebuilt chart object?), which an agent must infer before chaining to update_chart_categories.

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

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

Schema coverage is 100%, so per-parameter meaning is already documented; the description goes beyond it by stating that irrelevant counts are ignored per layout and by showing a worked combination of layout, rowCount, seatsPerRow, blocks, categoryLabels, stageKind and expectedUpdatedAt. It does not explain expectedUpdatedAt's concurrency semantics, but the schema does.

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

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

States a specific verb and resource with scope: 'Replace the whole draft with a complete venue (stage, sections, zones, floors) from a layout type and counts.' This clearly separates it from the incremental builders named later (add_row_block, add_ga_area, add_table_array, add_booth_array), so an agent can pick it without opening schemas.

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

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

Explicit 'Use when' (user describes a new venue), explicit 'Not for' (a chart you want to keep), named alternatives for extending a layout, and a follow-up sequence (update_chart_categories then validate_current_chart). Both the selection condition and the exclusion are stated outright.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds concrete scope to that flag: 'It replaces everything on the chart' tells the agent exactly what is lost, not just that something is destructive. It does not mention the optimistic-concurrency requirement implied by the required expectedUpdatedAt parameter, nor what the call returns, which keeps it from a 5.

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

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

Front-loaded with the core effect, then Use-when, then Not-for, then destructiveness, then a single concrete example. Every sentence performs a distinct job and there is 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 an 8-parameter destructive generator with no output schema, the description covers purpose, qualifying scope, exclusions, alternative routing, destruction scope, and a full example. The remaining gap is that it never says what comes back after the rebuild (new chart snapshot vs. summary) and does not flag in prose that expectedUpdatedAt must come from a fresh get_chart call, though the schema does.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, which sets the baseline at 3. The worked example is genuinely helpful because it shows a realistic value set (seatCount/rowCount pairing, stagePosition, categoryLabel, price, expectedUpdatedAt) that reveals how the fields combine, but the prose itself adds no semantics beyond the schema.

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

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

States a specific verb and effect ('Replace the whole draft with one block of straight rows facing a stage, with exactly the number of seats asked for and one category'), which precisely defines the generated shape. It also names what it is not (multi-block/aisle/table layouts) and points to build_semantic_venue, so an agent can separate it from that sibling without opening a schema.

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

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

Explicit 'Use when' clause gives the qualifying conditions (small simple room, lecture hall/screening room/ceremony, up to 500 seats, one price). The 'Not for' clause enumerates the excluded structures and names the correct alternative (build_semantic_venue), 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?

Annotations mark this as a non-read-only, non-idempotent write, and the description adds real behavioral context the annotations do not: the classification gates how far the asset can be traced and photos are untraceable. The provided example with expectedRevision null also hints at the optimistic-concurrency call pattern, though the description never states plainly that the result is persisted and that a repeat call overwrites the prior classification.

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

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

Purpose is front-loaded in the first clause, and the 'Use when / Next / Example' lines are quickly scannable. The example is long and largely re-encodes schema shape, which costs a little density, but each line still carries routing or formatting 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 six-required-parameter write tool with no output schema, the description covers purpose, position in the pipeline, the key domain constraint, and a valid payload. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it with a complete worked example that shows a real sourceClass value, an evidence value, a passing confidence, and expectedRevision null alongside the schema's 'null first; then current revision' note. It does not explain the enum distinctions in prose (e.g. scan-or-photo-of-plan vs physical-venue-photo), leaving those to the schema.

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

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

States a specific verb ('say what kind of image it is') plus the resource and enumerates the four classes inline, then explains the consequence ('this decides how far it can be traced'). An agent can distinguish this from read-side siblings like get_reference_source_classification 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 sequencing is given: 'Use when: after get_reference_overview' and 'Next: get_reference_regions', plus an exclusion ('Venue photos cannot be traced'). It does not name a competing alternative tool or say when classification should be skipped/re-done, so it stops short of full when/when-not 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?

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is largely covered. The description adds useful behavioral context that this is scoped deletion and that approved records should be retracted rather than deleted, though it does not detail cascading effects or permission requirements.

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

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

The description is compact and front-loaded: purpose first, then Use when, Not for, Next, and an example. Every line contributes directly to correct invocation.

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

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

Given full schema coverage, destructive annotations, and no output schema, the description provides enough information to call the tool correctly. The only minor gap is that it does not explain broader consequences of deletion or what the record deletion affects beyond the single scope.

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

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

Schema description coverage is 100%, so the schema already documents scope, floorId, objectId, seatIndex, and expectedUpdatedAt. The example clarifies a typical payload, but the description does not add semantic detail beyond the schema for the other parameters.

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

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

The description states a specific verb and resource: deleting a Verified View record at one scope. It also explicitly distinguishes this from retracting an approved record via the sibling retract_confidence_evidence, so an agent can route correctly without opening another schema.

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

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

It gives explicit when-to-use guidance ('a draft or old record should go'), an explicit when-not-to-use case ('withdrawing an approved one'), and names the correct alternative tool. The follow-up step to get_confidence_coverage is 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?

Annotations already declare destructiveHint=true and readOnlyHint=false; the description adds domain meaning by saying 'Replaces the current draft,' telling the agent concretely what is lost rather than just that the call is destructive. It also discloses that no seats are produced. It does not state what happens on a stale revision/updatedAt mismatch, which for a concurrency-guarded mutation would be worth one more clause.

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 behavioral claim is front-loaded in the first sentence, then partitioned into 'Use when,' 'Next,' and 'Example' labels. Every sentence carries a distinct fact; nothing is redundant with the title.

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

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

For a destructive, non-idempotent mutation with no output schema, the description supplies the precondition, the replacement semantics, and the follow-up path, plus a call example. The remaining gap is failure behavior (stale revision/updatedAt) and whether pre-existing seats or objects in the draft survive the replacement.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes slightly beyond by including a worked example with all three required parameters populated, showing realistic value shapes and how the guard fields travel together. It does not explain the semantics of expectedBlueprintRevision vs expectedUpdatedAt, but the schema already does.

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 (build) and resource (the approved outline into the chart) plus explicit scope boundaries: 'section shapes and stage, no seats yet.' The 'no seats yet' clause implicitly separates it from the seating-fill siblings (fill_sections_with_rows, insert_seating_block) without opening their 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?

Gives an explicit precondition ('Use when: after approve_reference_blueprint') and names the two valid successors (apply_reference_inventory or plan_reference_capacity). The agent knows both when to call it and what to call next, with no inference required.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent, closed-world operation. The description adds meaningful workflow behavior beyond annotations: the traced image must first be classified traceable, and the next step is get_reference_regions. It does not contradict the annotations.

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

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

The description is tightly structured and front-loaded: purpose first, then 'Use when', then 'Next', then a short example. Every line contributes actionable information with 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 fully schema-described configuration tool with annotations and no output schema, the description provides purpose, prerequisites, next step, and a payload example. A minor gap remains around expected return behavior and the optimistic-concurrency revision semantics, though the schema covers expectedRevision.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds value by explaining that geometryAssetId is the traced source while supplementalReferences are images that only add detail such as labels, counts, price legend, accessibility, and photos, which maps to the supplement purpose enum.

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 action and clearly names the resource: choosing the traced image plus supplemental detail-only images. It distinguishes the traced image from supplements and gives a concrete example payload, so 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 usage condition ('the user gave several images for one venue') and a prerequisite ('the traced one must be classified traceable first'). It also names the next tool, but does not state when-not-to-use or alternative tools for viewing/updating an existing set.

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

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

Annotations already disclose that this is not read-only, is idempotent, non-destructive, and closed-world. The description adds important behavioral context beyond annotations by saying the confirmation unlocks the picture tools. It does not detail failure behavior, but the gating effect is clearly 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?

The description is front-loaded with purpose, then immediately gives usage timing, next steps, and a concrete example. It is compact and every element helps an agent invoke the tool correctly.

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

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

For a four-parameter confirmation tool with no output schema, the description covers purpose, timing, successors, and a representative payload. It does not explain success/return behavior, but the unlocking effect and next-step guidance make it largely complete.

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

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

Schema description coverage is 100%, so each parameter is already documented in the schema. The example usefully demonstrates the expected payload shape, but the description does not add much semantic meaning beyond the schema's own field descriptions and patterns.

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 and resource: report what was read in the begin_vision_probe pictures. It clearly distinguishes this confirmation step from the sibling begin_vision_probe tool and explains that it unlocks picture 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 gives an explicit trigger ('right after begin_vision_probe') and names likely next tools (render_preview, prepare_chart_review, upload_reference_image). This leaves little ambiguity about when to invoke it.

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

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

Annotations already state this is a non-idempotent, non-destructive, closed-world write; the description adds the crucial behavioral fact that it switches the active chart and that the operation is refused on one-chart connections. It stops short of stating permission requirements or limits (e.g. max charts per workspace), 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?

Front-loaded purpose sentence followed by labeled Use when / Not for / Next / Example blocks; every line is actionable and there is 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 one-parameter creation tool with no output schema, the description covers purpose, side effects, refusal case, and the immediate next tools — everything an agent needs to call it correctly and continue the workflow.

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 100% schema description coverage and a single required 'name' parameter, the schema already carries the semantics; the worked example ('Riverside Theatre: Main Hall') reinforces the naming format but adds little beyond the schema's own example and the 120-char max. Baseline 3 applies.

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

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

A specific verb and resource ('create a new empty chart in the workspace') plus the key side effect of switching to it, which distinguishes it from builders like build_simple_chart or build_semantic_venue that populate an existing chart.

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

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

Explicit 'Use when' and 'Not for' clauses name the exclusion condition (one-chart connections are refused) and route to alternatives; the 'Next' line chains to get_chart then build_semantic_venue/build_simple_chart, so the agent knows the expected follow-up sequence.

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

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

Annotations already declare the write/non-destructive/non-idempotent profile; the description adds real value on top by disclosing the validation failure mode for colour ('the error suggests one') and pointing to the expectedUpdatedAt concurrency token via get_chart. It does not describe what the call returns (e.g. the new category key), which matters for a creation tool with no output 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 the action, then cleanly sectioned as Use when / Not for / Next / Example. Every sentence carries routing or payload 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?

For a non-destructive mutation with annotations and a fully described schema, the description covers purpose, prerequisites (via expectedUpdatedAt source), sibling choice, and next step. The remaining gap is the return value / how to obtain the new category key, which the follow-up advice only partially bridges.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by supplying a full worked payload and by framing `tiers` as ticket types with a child/senior flavour, which the schema only hints at via its `restriction` enum. It doesn't add new constraints beyond the schema.

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

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

States a specific verb and resource ('Add a price category') plus the fields that define it (colour, optional price, ticket types). It is immediately distinguishable from sibling update_chart_categories, which it names explicitly.

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

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

Provides explicit 'Use when: a new price level is needed', 'Not for: editing one (use update_chart_categories)', and a follow-up step ('Next: assign it with categoryKey on update_rows or update_sections'). This covers when, when-not, the alternative, and the downstream flow.

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

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

Annotations already declare mutation, non-destructive, and non-idempotent, so the safety profile is covered. The description adds a genuinely useful behavioral fact beyond that: creating the zone does not assign sections, so a separate update_sections call with the returned zoneId is required to complete the grouping.

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

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

Front-loaded with the purpose, then usage condition, then the required follow-up call, then a compact payload example. Every line earns its place and nothing is padded.

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

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

For a non-destructive create with no output schema, the description covers purpose, trigger, and next step. The one residual gap is that it implies the new zoneId comes back in the response without stating the return shape or whether other zone data is echoed.

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

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

Schema description coverage is 100%, with label, color, expectedUpdatedAt and the const useGlobalFocal all documented, so the baseline is 3. The inline example repeats the same field set without adding semantics such as label uniqueness or the concurrency meaning of expectedUpdatedAt beyond what the schema already states.

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

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

Specific verb+resource ('Create a zone') plus a definition of what a zone actually is ('a named group of sections like Lower Bowl, for zooming and grouping'). This distinguishes it cleanly from siblings update_chart_zones and delete_chart_zone, which operate on existing zones.

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 'Use when' clause with a concrete example ('group 101-120 as the Lower Bowl') gives a clear trigger condition, and 'Next: update_sections with the new zoneId' documents the follow-up step. It does not explicitly contrast with update_chart_zones for the case where a zone already exists, so no exclusion 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?

Beyond the annotations (readOnly=false, idempotent=true, destructive=false), the description discloses that the created event is a non-selling draft requiring a separate open_sales step, that a permission is required, and that retrying produces exactly one event. It also explains the test-to-live transition via set_event_mode, which the annotations do not convey.

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

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

Front-loaded with the core action and its draft-state constraint, then organized into labeled 'Use when', 'Not for', 'Next' and 'Example' blocks. Every line carries operational information; there is 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 mutating, no-output-schema tool in a dense workflow of ~140 siblings, the description supplies the lifecycle context an agent needs: draft creation, what blocks selling, how sales open, and how test events go live. Nothing essential to calling 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 100%, so the schema already defines all seven parameters; the description adds value by giving a realistic payload example that shows how name, startsAt and timezone are expected to look together. It does not elaborate on mode, chartId or idempotencyKey semantics beyond what the schema already states, so it exceeds baseline without being 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 and resource ('Create a new event (show date) from a published chart') and immediately adds the key scope qualifier that the result is a draft in setup with nothing on sale. It explicitly sets itself apart from the nearest sibling (duplicate_event) rather than leaving the distinction to inference.

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

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

Provides concrete 'Use when' triggers with sample utterances, an explicit 'Not for' case routed to duplicate_event, required permission ('Create and run events'), and a 'Next' chain pointing at get_event and plan_inventory_change. Both when-to-use and when-not-to-use are covered with named alternatives.

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

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

Annotations already declare non-readonly, non-destructive, non-idempotent behavior; the description adds meaningful context beyond them by stating 'The chart is not changed' and that the result is a draft, version 1. It stops short of describing what happens on duplicate labels, whether creation is reversible, or what the final state transition requires.

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?

Occupies four tight lines: definition, usage trigger, next step, example. The most decision-relevant fact (chart unchanged, draft) is front-loaded and the example replaces prose that would otherwise be needed.

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 two-parameter tool with a deeply nested overlay object, the description supplies purpose, trigger, sequencing and a call example, and no output schema means no return-value explanation is owed. The omission of productionElements and its occlusion/height semantics is the remaining gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the worked example goes further by showing a concrete payload that maps 'label' to a setup name and demonstrates the id:index format of productionKillSeatIds. The optional nested 'productionElements' array (the most intricate part of the schema) is never mentioned, keeping this below a 5.

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

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

States a specific verb and resource (create an event configuration) plus its object semantics — a setup listing production shapes and the seats they take off sale — and clarifies output state (version 1, draft). This clearly distinguishes it from sibling mutations like update_event_configuration and the chart-editing 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?

Gives an explicit trigger ('the venue has different setups, e.g. "the concert stage kills rows A-C"') and a concrete next step ('Next: submit_event_configuration'), which routes the agent through the workflow. It does not state when not to use it — e.g. when an existing configuration should be modified via update_event_configuration instead of creating a new one.

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

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

Annotations declare the write/idempotent/openWorld profile, and the description adds meaningful context beyond them: this is an asynchronous job whose result must be fetched via get_panorama_manifest_job and applied manually by a human in Designer, plus a concurrency token (expectedUpdatedAt) guarding the write. It does not state size/rate limits or job failure behavior, keeping it short of a 5.

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

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

Labelled lines (Use when / Not for / Next / Example) front-load the routing decision before the payload detail. The long example line earns its space by encoding the column contract that would otherwise take multiple sentences.

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 write/job tool with no output schema, the description covers the async follow-up and human application step. It never explicitly says what the create call returns (a job handle/id), which leaves a small gap for an agent deciding what to do with the response.

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

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

Schema coverage is 100%, so the schema already documents all three parameters; baseline would be 3. The description adds a concrete worked manifest payload showing the required column set and the expected format, which is genuinely additive for constructing manifestText. The expectedUpdatedAt meaning remains schema-documented only.

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

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

States a specific verb and resource — queue a manifest job for a CSV/JSON list of 360° seat-view photos — and immediately scopes each row to venue, floor, section, row or seat. It also names the sibling it is not (set_view_from_seat_fallback) so the tool is distinguishable without opening the schema.

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

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

Explicit 'Use when: many photos at HTTPS links', an explicit 'Not for: one photo (use set_view_from_seat_fallback)' exclusion with the alternative named, plus a 'Next: get_panorama_manifest_job' follow-up step and the note that a person applies the result in Designer. Nothing about when to use it is left to inference.

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

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

Annotations already flag destructiveHint=true and non-idempotent, so the safety profile is known. The description adds genuine value beyond that: it discloses exactly what is affected (seats, tables, areas) and where they go when moveSeatsTo is supplied, plus two inviolable business constraints (last category, traced plan). It still doesn't say explicitly that the deletion is irreversible or what happens to inventory left behind without moveSeatsTo beyond the unused-category rule.

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

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

Three short clauses plus a usage line and a compact JSON example — every element earns its place. The destructive effect and the moveSeatsTo branch are front-loaded in the first sentence.

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

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

For a 3-parameter destructive mutation with no output schema, the description covers effect, inventory relocation, preconditions, when to reach for it, and a sample call — everything needed to invoke it correctly. Annotations carry the safety signalling, so nothing material is missing.

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

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

Schema coverage is 100%, so 3 would be the baseline, but the description explains the *effect* of moveSeatsTo (seats, tables and areas are relocated before deletion) rather than just its type, and the example anchors expectedUpdatedAt as a real value with a concrete category key. That is meaningfully more than the schema's one-line parameter blurbs.

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 ("Delete a category") plus the exact scope of the deletion (its seats, tables and areas). It is clearly distinguishable from siblings like delete_chart_objects and delete_chart_zone, which operate on different resources.

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 ("Use when: a price level should go, e.g. 'merge Value into Standard'") and hard preconditions ("Never the last one or one from a traced plan"). It does not name an alternative sibling tool (e.g. update_chart_categories for renaming rather than removing), so it stops just short of full 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description earns credit for adding non-redundant behavior: dry-run-by-default via confirmRemove and that deletion 'cannot be undone'. It stops short of explaining what the preview response contains or how expectedUpdatedAt conflicts surface.

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

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

Four short lines with the scope, use trigger, exclusion, and a JSON example — all front-loaded, no filler. The preview/irreversibility caveat is placed where it will be read before invocation.

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

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

For a destructive mutation with no output schema, the description covers the safety-relevant unknowns (preview mode, irreversibility) and the ID source. Only the preview return shape and update-timestamp failure handling are unaddressed, which is minor given the 100%-covered schema.

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

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

Schema description coverage is 100%, so every parameter is already documented, and the description mostly reinforces it. The worked example does show confirmRemove=true alongside expectedUpdatedAt, hinting at the optimistic-concurrency pairing, but floorId and the meaning of a mismatch are left entirely to the schema.

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

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

States a specific verb and resource ('Delete whole objects by id') and enumerates the covered object types (rows, tables, booths, standing areas, sections, shapes, texts). It also explicitly excludes a sibling: 'Not for: single seats (use update_seats).'

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

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

Provides an explicit use-when example ('remove the balcony'), an exclusion routing to update_seats, and the key operational condition that omitting confirmRemove only previews. This is close to the full when/when-not/alternative triad.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered; the description adds genuinely new behavior — sections are preserved, and section assignments may need explicit confirmation. It stops short of saying whether the delete is recoverable or what happens to rows/seats inside the zone.

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

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

Three compact lines, front-loaded with the behavior and the trigger before the example. The example earns most of its space as a call template, but is marginally redundant given full schema coverage.

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, non-idempotent mutation with no output schema, the description covers the post-condition, the conditional parameter, and the concurrency token in the example. Missing are permission requirements, stale-expectedUpdatedAt failure behavior, and the fate of objects nested inside the zone.

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

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

Schema coverage is 100%, so all three parameters are already documented, including identical wording for confirmClearSectionAssignments ("Required if sections use it"). The description's only addition is a concrete example payload, which slightly conflicts with the conditional phrasing by always showing the flag as true. Baseline 3 applies.

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

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

Specific verb+resource ("Delete a zone") plus the non-obvious consequence that sections survive, which distinguishes it from delete_chart_objects and delete_chart_category by implication. It never names those siblings explicitly, so the differentiation rests on the word "zone" alone.

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

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

"Use when: a group is no longer wanted" gives an explicit trigger condition, and the confirmClearSectionAssignments note states a prerequisite. There is no when-not guidance and no routing to update_chart_zones or delete_chart_category as alternatives.

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

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

Annotations already mark this as read-only, idempotent, non-destructive, and closed-world. The description adds substantial context beyond them: the vision probe prerequisite, the reference_analysis_pending error with retryAfterSeconds, and the fact that the tool returns both numbers and a PNG diff image.

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 tightly structured and front-loaded: the core measurement is first, followed by succinct Use when / Not for / Next / Error sections. Every line contributes 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?

For a read-only comparison tool with one fully documented optional parameter, the description is complete enough to call correctly. It covers purpose, prerequisites, exclusions, output shape, next steps, and the asynchronous pending state.

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?

There is only one optional parameter, floorId, and schema description coverage is 100%, so the schema already explains it fully. The description does not discuss floorId or its default behavior, which is acceptable given the high schema coverage but adds no parameter-level value.

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: measuring a traced chart against its floor-plan image, with named comparison dimensions (outline overlap, distance, section/zone/stage/category/seat-count coverage). It is clearly distinguished from sibling validate_current_chart and from charts without a traced plan.

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

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

Explicitly says when to use it (after render_preview on a chart traced from an image), when not to use it (charts with no traced plan; general quality checks should use validate_current_chart), and what to do next (restore_reference_sections then validate_current_chart). It also names the prerequisite vision probe.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false; the description adds that the source section must be empty, that partCount is bounded 2-60, and that expectedUpdatedAt (from get_chart) guards the mutation. It stops short of saying the source section is consumed/replaced or what error a stale expectedUpdatedAt produces.

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

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

Four short, front-loaded lines: what it does, when to use it, what to do next, and a concrete call example. No filler sentences and nothing restated from the schema.

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

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

For a destructive, non-idempotent 9-parameter mutation with no output schema, the description supplies the workflow position (before fill_sections_with_rows) and the concurrency-token source, which is enough to call it safely. It omits what happens to the original section's identity and the failure mode on stale expectedUpdatedAt.

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

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

Schema coverage is 100%, so the baseline is 3, but the worked example shows the required parameters in a realistic combination (mode=radial, partCount=12, aisleWidth=44, expectedUpdatedAt as a timestamp) and ties expectedUpdatedAt to get_chart. It does not explain the non-radial modes or the label* parameters beyond the schema.

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

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

States a specific verb and resource ('Split one empty section into 2-60 named sections with aisles'), plus the two geometric modes (radial slices / straight bands). This clearly separates it from siblings like repeat_section_radially, mirror_section_assembly, or fill_sections_with_rows.

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

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

Gives a concrete use-when example ('cut the lower bowl into 12 sections') and names the follow-up step (fill_sections_with_rows). It does not say when to prefer alternatives such as repeat_section_radially or mirror_section_assembly, so exclusions are missing.

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

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

Beyond annotations it discloses the substantive behavior: the copy lands as a draft in setup, prices/releases/blocks/settings transfer while orders and sales do not, and retrying the same call produces only one copy. It also adds the authorization requirement annotations cannot express.

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 behavior, then labeled Use when / Next / Example blocks. Every sentence carries distinct information with no restatement of the name or schema.

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

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

For a non-destructive, idempotent mutation with a fully documented schema and no output schema, the description covers scope, side effects, permissions and next steps. It stops short of saying what identifying handle the copy returns, which would be the last useful detail.

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

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

Schema coverage is 100%, so the schema already documents all four parameters including defaults. The description still adds value by supplying a concrete example payload showing the eventKey and offset-bearing ISO 8601 startsAt format.

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 (copy an event) plus the resulting state (new date, draft in setup) and delineates exactly what is carried over versus omitted. An agent can distinguish this from create_event or update_event 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?

"Use when" gives concrete natural-language triggers and names the required permission scope ("Create and run events"). It also prescribes the follow-up chain (get_event, then plan_inventory_change with open_sales), though it never explicitly contrasts against create_event as an alternative.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-structured behavior: the operation is atomic ('all or nothing') and bounded to 2-60 sections. It stops short of warning what happens to sections that already have rows (only the schema's replaceExisting field hints at this) or what a failure returns.

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

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

Three terse labeled lines plus one example: behavior and cardinality first, then usage, then counter-usage, then a payload sample. No filler sentences.

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-parameter destructive batch mutation with no output schema, the description covers scope, atomicity, the alternative tool, and a sample payload. It omits conflict behavior for stale expectedUpdatedAt and what the caller gets back on partial rejection, which would matter at this complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a concrete composite example showing how targets, categoryKey, and expectedUpdatedAt are assembled together, which is useful for a required array-of-objects parameter; the expectedUpdatedAt/get_chart relationship itself is already documented in the schema.

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

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

States a specific verb and resource plus the cardinality constraint: 'Fill 2-60 sections with rows to a seat count each; all or nothing.' It also explicitly contrasts with the sibling fill_section_with_rows, so an agent can distinguish the two without opening either schema.

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

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

Provides explicit when-to-use ('several empty sections with known capacities'), explicit when-not ('one section'), and names the alternative tool to use instead. Nothing is left to inference.

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

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

Annotations already declare destructive and non-idempotent behavior. The description adds important preconditions: it refuses to fill a section that has rows unless replaceExisting is used, and replaceExisting rebuilds existing rows. That is exactly the kind of behavioral context 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?

The description is short, front-loaded, and structured around use-when, refusal, not-for, and example. Every sentence contributes to selecting or invoking the tool correctly.

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 mutation tool with annotations and no output schema, the description covers the essential selection, refusal, and replacement behavior. It does not describe the return value or post-fill validation, but the critical invocation constraints are 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 description coverage is 100%, so the schema already defines every parameter and its defaults. The description adds a useful invocation example but otherwise does not explain parameter semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource: fill one existing section with rows that fit its outline. It also explicitly distinguishes this from the sibling fill_sections_with_rows, which handles several sections.

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

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

It gives explicit use conditions (section is empty, e.g. "fill 104 with 350 seats"), refusal behavior when rows already exist unless replaceExisting is set, and a direct alternative for multiple sections.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description still adds genuinely new behavior: a workspace connection searches every chart, so select_chart is unnecessary. It stops short of describing pagination behavior or result caps beyond what the cursor/limit schema fields imply.

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 one-line purpose, then labelled Use when / Not for / Next / Example blocks. Every sentence carries routing or parameter information; nothing is 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?

For a 6-param, all-optional search tool with no output schema, the description supplies the return shape (seat counts by state, chart) and the follow-up calls, and the schema covers filters and paging. An agent can call this correctly without further context.

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns one step more by mapping natural-language user intent to specific parameters and giving a concrete example that shows query combined with a from/to range.

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 (find events) plus the filter dimensions (name, start date, sales state) and what each result carries (sold/held/blocked/available seats and its chart). This is clearly separable from get_event (single event) and list_chart_events in the sibling list.

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

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

Explicit 'Use when' with concrete user phrasings ('the Friday show', 'Diwali night in November'), an explicit 'Not for' routing to get_event_sections, and a 'Next:' pointer to get_seats/get_event_sections. It also rules out a tempting alternative by noting no select_chart is needed.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the description's added value is the 20-result cap, 'newest first' ordering, and the permission gate — all behavior an agent cannot infer from the schema. It does not discuss truncation behavior when more than 20 matches exist, but the core traits are disclosed.

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 capability and limits, then use-cases, prerequisite, next step, and an example — each line is a distinct, actionable unit with no filler.

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

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

With no output schema, the description still conveys the return shape indirectly (max 20 results, newest-first ordering, results carry an orderRef for get_order). It stops short of describing result fields or how partial/ambiguous matches are returned, but is otherwise complete for a 2-param search tool.

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

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

Schema coverage is 100% and both parameters already document their accepted values, so the description largely restates them. The worked example ({"eventKey": "ev_1350a828b5ff", "query": "priya@example.com"}) adds mild concreteness but no new semantics about matching behavior or ambiguity handling.

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

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

States a specific verb ('Find') and resource ('an event's orders') with the exact lookup keys (order reference, ticket code, name, email, phone, seat). The parenthetical 'up to 20, newest first' bounds scope, which cleanly separates it from list_orders (unbounded listing) and get_order (single-record 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 'Use when:' clause gives concrete caller scenarios ('I booked under Priya', 'who has seat F-4?') and the Orders permission prerequisite is stated explicitly. It also routes forward ('Next: get_order with its orderRef'), though it never explicitly contrasts with list_orders for the browse-all case or states a when-not condition.

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

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

Annotations already declare the read-only, idempotent, non-destructive profile, and the description adds valuable behavioral context by naming the content returned: playbooks, permission boundaries, unsupported cases, and per-feature limits. This is exactly the orientation information an agent needs before selecting other tools.

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

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

The description is front-loaded with 'Start here', then succinctly covers what is returned, when to use it, and what to do next. Every sentence earns its place and the structure maps directly to an agent's decision process.

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 empty input schema, no output schema, and rich annotations, the description is complete for an orientation tool. It explains what categories of information come back and how to proceed, which is sufficient for calling and using it.

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

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

The tool has zero parameters, so the baseline is 4. There is no parameter meaning to explain, and the description correctly does not invent any.

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

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

The description states a specific verb and resource: returns playbooks, connection capabilities, limitations, and feature limits. 'Start here' and the enumerated job types make its orientation role unmistakable among the many sibling 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 explicitly says when to use it ('at the start of every conversation, before choosing tools') and names the next tool to use ('get_chart'). This gives an agent a clear routing decision instead of leaving sequencing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so safety is covered. The description adds real value beyond that by disclosing the payload contents (seats, buyability, price list, history) and by pointing at the next workflow step. It does not mention result size or pagination behavior for channels with many seats.

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

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

Purpose comes first, then usage examples, then the next step, then a compact example object. Every line carries information an agent can act on; there is no filler or repetition of the schema.

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

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

For a two-parameter read tool with no output schema, the description covers what it does, when to call it, what comes back at a high level, and what to do next. The only gap is the absence of any note on ordering or volume of the returned seat/price/history data.

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

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

Schema coverage is 100% and each parameter already documents its source (eventKey from list_chart_events, channelId from list_channels). The description adds a concrete invocation example with real-shaped values, which reinforces the dependency chain rather than merely restating the schema.

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

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

The description uses a specific verb and resource ("Show one sales channel") and enumerates exactly what is returned: seats by section, buyer entitlements, own price list, and history. This clearly separates it from list_channels (plural listing), though it does not explicitly distinguish itself from get_channel_report or get_event_pricing, which an agent must infer.

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 supplies two concrete trigger questions ("which seats does the sponsor channel hold?", "what changed on the agency channel?") and names the natural follow-up tool, plan_inventory_change. What is missing is a negative case — when to reach for get_channel_report or list_channels instead — so the agent still has to infer the boundary.

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

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

Annotations already cover the safety profile (readOnly/idempotent/non-destructive), so the bar is lower, and the description adds genuinely non-obvious behavior: monetary values only appear when the connection has 'Read reports' permission, otherwise counts only. That permission-dependent output shape is exactly the kind of context annotations cannot carry. It does not describe response structure or any limits, keeping it at 4.

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

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

Front-loaded with the core purpose, then usage, then an example - a sensible ordering with no filler. The phrasing is slightly compressed ('beside each one's seats'), but nothing is wasted.

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

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

For a two-parameter read-only report with full schema coverage and no output schema, the description covers purpose, trigger conditions, permission-dependent output, and an example call. Only the shape of the returned rows is left implicit, which is a minor gap.

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

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

Schema coverage is 100%, so the schema already defines both parameters, including 'since' as epoch ms and eventKey as coming from list_chart_events. The description restates 'since' as counting seats sold since that time and supplies an example payload, adding only marginal meaning beyond the schema; baseline 3 applies.

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

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

States a specific verb ('report') and resource ('sales per sales channel') and enumerates the reported measures (seats, sell-through, seats sold since). It is clearly distinguishable from get_event_report and get_channel by its per-channel dimension, though it never names those siblings explicitly.

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

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

The 'Use when' line gives two concrete natural-language phrasings ('how is the agency selling?', 'what did each channel sell this week?') that map intent to tool. It supplies no exclusions or explicit alternative tools, so it stops short of full routing guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real behavior: large charts are truncated to a summary and "view: full" should only be requested when every seat is needed. It also discloses the optimistic-concurrency token (meta.updatedAt) that guards subsequent mutations.

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 payload, then clearly labeled Use when / Not for / Next blocks. 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?

No output schema exists, so the description correctly fills that gap by enumerating returned object types and the summary-vs-full truncation, and it covers the concurrency workflow an agent needs to safely follow up.

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 one parameter at 100% schema coverage the baseline is 3; the description earns more by giving the decision criterion behind the enum — only ask for "full" if you actually need every seat, since big charts default to a summary.

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?

"Read the chart" plus an explicit enumeration of returned entities (categories, floors, sections, rows, tables, booths, GA areas, shapes, texts) with ids makes the resource and output unambiguous. It is clearly distinguishable from validate_current_chart and render_preview, which are named.

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 triggers (starting work, before any change, after a conflict error) and explicit exclusions routing quality checks to validate_current_chart and visual inspection to render_preview. It even states the follow-up action of passing meta.updatedAt as expectedUpdatedAt.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds genuine behavior not in annotations — it re-fetches the stored images and performs a staleness comparison ('say if the chart changed since'), and explains the reconnect scenario that motivates the call. It leaves ambiguous what 'since' is measured against and what happens if the review is missing.

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

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

Three short lines, front-loaded with the action, followed by usage and a concrete example — no filler. The example value is slightly redundant with the schema pattern, keeping it from a 5.

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

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

With no output schema, the description does carry return-value burden and partially discharges it by naming the outputs (the review, its pictures, a changed/unchanged signal). What remains thin is the freshness comparison semantics and error behavior, but for a single-param read tool this is close to sufficient.

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?

Only one parameter and schema coverage is 100%, with the schema already documenting the crp_ pattern and 'From prepare_chart_review; default latest.' The description's example value restates the schema rather than adding new meaning such as what 'latest' resolves to.

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 ('Fetch') and resource ('a review and its pictures'), plus a secondary capability ('say if the chart changed since'). This distinguishes it from prepare_chart_review, which the schema names as the producer of the id, though the description itself never contrasts the two.

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 trigger conditions are given: 'after a reconnect, or before publishing.' That is real when-to-use guidance, but no when-not or named alternative (e.g. prepare_chart_review vs publish_reviewed_chart) is offered, and 'before publishing' never names publish_reviewed_chart directly.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds that results are scoped to seats missing Verified View coverage plus open report counts, which is useful return-content context given there is no output schema, but it says nothing about result size, formatting, or how the event defaults are resolved beyond 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?

Three compact lines: what it shows, when to call it, and a copy-pasteable example. Purpose is front-loaded and every line earns its place with 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 single-optional-parameter read tool with no output schema, the description covers purpose, timing, and the shape of the result well enough to call correctly. Minor gaps remain around the scope of "coverage" (whole event vs. section) and result volume.

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

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

Schema coverage is 100% and the single eventId parameter is documented with a default ("default: the draft"), so the schema does the explaining. The description's example {"eventId": "ev_1350a828b5ff"} only illustrates the format and does not clarify the default behavior the schema hints at, so the baseline of 3 applies.

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

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

States a specific verb and two concrete outputs: seats lacking a Verified View record, and the count of open buyer reports. That is far more than a restated title. It doesn't name a sibling (e.g., list_view_evidence_reports or get_chart_review) to differentiate, 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?

"Use when: before an on-sale or after reports" gives clear temporal triggers, which is exactly the context an agent needs to schedule this call. There are no explicit exclusions or named alternatives, so it falls short of 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds real context: the required authorization scope and the explicit exclusion of buyer data, plus the readiness narrative it returns. Return format details (pagination, field shapes) are not covered, but the annotations and field enumeration largely compensate.

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 what is returned, then when-to-use, prerequisites, and next steps in labeled fragments. Dense but every clause carries information; the example line is the only mildly redundant element given the schema.

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

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

With no output schema, the description carries the burden of explaining return content, and it does so by listing the concrete domains (settings, sales state, seat counts, checkout, readiness blockers). It is close to complete for a single-parameter read tool, with only low-level response details absent.

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

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

Schema coverage is 100% and the eventKey property already documents its source ('Key from find_events or list_chart_events'). The description's example object restates this rather than adding new meaning such as format constraints or lookup failure behavior.

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

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

States a specific verb (read) plus the resource (one event) and enumerates the content returned: settings, sales state, seat counts, checkout details, and sales-readiness blockers. The 'No buyer data' clause draws a useful boundary, though it does not explicitly contrast with near-neighbors like get_event_pricing or get_event_report.

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 triggers ('before opening sales', 'is Friday ready to go on sale?', 'what time does the gala start?'), states the permission prerequisite ('Needs Create and run events'), and routes to next steps (update_event, plan_inventory_change with open_sales/close_sales/reopen_sales).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered structurally; the description adds the useful behavioral fact that this is a comparison against the latest published chart version and is a precursor to a move/update step. It does not describe what the check returns (e.g. drift status, version identifiers), which is left implicit.

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

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

Three tight lines: purpose first, then trigger, then next-step routing, with a compact example. No filler, and the most important information is front-loaded.

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

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

For a single-parameter read-only check, the description covers purpose, timing, and follow-up actions well. The one remaining gap is the return shape — with no output schema, the agent is not told what a 'fresh' vs 'stale' result looks like — but this is a minor omission for a diagnostic tool.

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

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

Schema coverage is 100% and the parameter is documented as 'Key from list_chart_events', so the schema already carries the semantics (baseline 3). The description goes slightly beyond by supplying a concrete worked example ({"eventKey": "ev_1350a828b5ff"}), which usefully confirms the expected key format.

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 ('Check whether an event uses an older published chart version') and explicitly frames the outcome ('could move to the latest'). This is clearly distinguishable from siblings like update_event_chart and move_event_to_chart, which the description names separately.

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 ('Use when: after publishing chart changes') and routes to the correct next tool conditioned on lifecycle state ('on sale' -> plan_inventory_change / move_event_to_chart; 'in setup' -> update_event_chart). This is the when-to-use plus alternatives pattern at its best.

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