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

With no annotations provided, the description carries the full burden and does so well: it discloses the dimension scale gate and its refusal behavior, the tag-minting-on-first-touch behavior, the no-review-gate rule, coordinate space (image px at 2.0 scale, PDF pt x2, origin top-left), and colour/PDF/report propagation. The main omission is any statement about what happens on failure for non-dimension types or whether annotations can be re-edited, so it is not quite exhaustive.

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

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

It is front-loaded with the core purpose, but the paragraph is dense, parenthesis-heavy and carries a reference marker (#150) plus redundant restatement ('it touches no quantity' appears twice in different words). For a 10-parameter, 7-type tool some length is warranted, but several clauses do not earn their place.

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

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

An output schema exists, so return values need not be documented, and the description covers everything else an agent needs: type-to-parameter requirements, coordinate conventions, gate behavior, and condition/scope semantics. Nothing material to calling 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 already 100%, so the baseline would be 3; however the description adds genuine meaning beyond the schema by explaining the dimension's measured-endpoint semantics and the scale gate, the bubble radius default, and the condition tag's scope consequences. The per-type parameter mapping largely restates what the enum description already says, keeping this short of a 5.

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

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

The first sentence states a specific verb and resource ('Place an annotation on a sheet') and immediately differentiates it from the measurement tools ('a note ABOUT the work, never a measurement of it'). It then enumerates all seven annotation types and their geometry, so an agent can tell exactly what this does versus nearby siblings like measure_polygon or edit_annotation.

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

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

It states explicitly when to attach a note to a condition tag ('what makes it part of that SCOPE rather than a floating remark') and when to omit it ('for a note about the sheet itself'). It also names the alternative route for dimensions ('set_scale first') and clarifies there is no review gate, covering when-not as well as when.

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

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

No annotations exist, so the description carries full burden. It discloses key behavioral traits: deterministic (not a re-prompt), uses the same rules.ts engine as Preview, commits as a single batch reversible by undo_last, marked reviewed:false, includes per-rule disclosure in the reply, and is idempotent. It also notes refusal when no rules are imported and skipped_sheets for uncalibrated/raster sheets.

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

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

The description is long but every sentence contributes essential behavioral context for a tool with no annotations and nuanced semantics. It is front-loaded with the core purpose then layers details about evaluation, commit, idempotency, import gate, and skipped sheets, making it dense but not wasteful.

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 fully covers the tool's behavior for its single-parameter interface: it explains the default scope, output behavior (per-rule disclosure serving as preview), error conditions (refuses without imports), and edge cases (skipped sheets). An output schema exists, and the description complements it by describing the meaning of skipped_sheets and the preview nature of the reply.

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

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

Schema description coverage is 100% and the tool has only one optional 'sheet' parameter. The description restates the schema ('Pass sheet to scan one sheet; omit it to scan every sheet holding the rules' rooms') without adding new meaning, so it stays at the baseline for high schema coverage.

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

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

The description clearly states the tool re-runs correction rules, identifying them as deterministic predicates ('enclosed linework islands under a size cap') and ties them to the canvas's Apply action. It distinguishes from siblings by noting rules arrive only via import_takeoff and that undo_last can reverse the batch.

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 guidance is provided: re-running after new rooms commit is the intended workflow, and it is safe due to idempotency. The description also contrasts with alternatives: rules only via import_takeoff, preview via view_sheet, and undo via undo_last.

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

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

No annotations exist, so the description carries the full burden and does so richly: deterministic/no-seed behavior, the identity rule for what counts vs. is withheld, commit producing ONE undo step, refusal-honest scan/sheet behavior, and the coordinate space. This is far beyond what structured fields provide.

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

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

Front-loaded with the core action, but the body is a dense run-on paragraph packed with jargon, heavy em-dash nesting, and a late equipment-marks addendum. Most sentences carry information, yet the structure makes it hard to parse and is longer than it needs to be.

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

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

With an output schema present, return values needn't be explained, and the description still covers the counting rule, exclusions, refusals, commit/undo, coordinate frame, and the special equipment-mark case. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: how marks default to schedule row keys, compound-row behavior ('R1 / E1' answers for both), the citation of a source row, and the commit-per-mark semantics. This meaningfully exceeds the schema's own strings.

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 (census/count) and resource (VALUE-ANNOTATED mark tags per schedule mark) and names the sibling it is not (sweep_schedule_row). An agent can distinguish it from the geometry-matching alternative 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?

Explicitly contrasts with sweep_schedule_row ('THAT tool is for marks drawn ON their marker with no value... this one is for annotated devices'), and states when marks should be stated vs. defaulted. Refusal conditions (scans, no mark-shaped rows, non-plan sheets) are spelled out.

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

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

With no annotations, the description fully carries the behavioral burden: it discloses the register sequence (RFI-001, …), default status ('open'), date handling, the agent origin record and 'PENDING' state pending human acceptance, printing behavior in the marked set, markup linking effects, and that the action is journaled and undoable. This is exceptionally thorough for a mutation tool.

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

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

The description is dense but every sentence earns its place: it front-loads purpose and conditions, then systematically covers behavior, linking, and journaling. There is no filler or repetition, and the information is logically ordered for an agent.

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

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

Given the absence of annotations and the presence of an output schema (which handles return values), the description provides all necessary context for correct invocation: when to use it, how it behaves, what state it creates, and how linked markups affect downstream reporting. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds significant meaning for markup_ids (explaining how to link annotations and the resulting RFI number propagation) but adds little beyond the schema for title, question, and sheet. The net value beyond structured data is moderate.

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

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

The description opens with a precise verb+resource ('Raise an RFI') and immediately defines the specific conditions for its use, distinguishing it from prose or other tracking methods. The detailed scenario examples make the purpose unmistakable 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 clearly states when to use the tool ('when the drawing set contradicts itself or cannot answer a question') and explicitly prefers it over describing the conflict in prose. However, it does not name an alternative sibling tool (e.g., resolve_rfi or list_rfis) for related tasks, so the routing guidance is strong but not exhaustive.

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

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

No annotations are provided, so the description carries the full burden; it discloses mutation semantics, one journal entry, undo_last behavior, delete_shape reverting the cut, multi-cut rebuild from the pristine snapshot, and multiple refusal rules. It also explains clipping versus subtracting for open runs and exact quantity effects, which is far beyond what structured fields provide.

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

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

Front-loads the core purpose, but the description is far longer than typical and packed with parenthetical references, asides, and repeated framing. Much content is substantive for a complex tool, yet the density and length hurt scannability, making it only adequately concise.

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

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

Given the absence of annotations and the tool's complexity, the description covers behavior, refusals, undo semantics, alternatives, and coordinate space exhaustively. An output schema exists, so return values need not be described; nothing critical seems 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 documents verts and parent_shape_id. The description adds valuable coordinate-frame semantics (image px at render scale 2.0, PDF pt × 2, origin top-left, y down) and distinguishes area cuts from run clipping, going meaningfully 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: cutting a real hole in a committed floor_area shape or clipping an open run. It explicitly differentiates from measure_polygon role:'deduct' and edit_shape for boundary corrections, so an agent can identify the tool without opening sibling schemas.

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

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

Explicit when-to-use guidance: column, floor drain, island of casework inside a room; names measure_polygon as the alternative for independent deductions. It also lists refusal conditions and alternative tools (edit_shape the parent, trace pieces as rooms, use measure_line), giving clear routing.

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

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

With no annotations, the description carries the full behavioral burden and does so richly: tombstone semantics (record stays, number reserved, register prints a gap), link handling (markups keep note, lose link), journaling, and reversibility via undo_last. This is well beyond what structured fields provide.

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

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

Front-loads the core action and scoping within the first clause, and most sentences earn their place by disclosing behavior. Slightly verbose with rhetorical flourish ('would be a lie'), but not wasteful enough to hurt.

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

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

Output schema exists so return values need not be explained, and annotations are absent but fully compensated by the description's coverage of tombstoning, links, journaling, and undo. An agent has everything needed to call it correctly.

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

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

Only one parameter with 100% schema description coverage ('Record id from create_rfi or list_rfis'), so the schema already documents it fully. The description adds no syntax or format beyond what the schema states, so 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+resource ('Withdraw an RFI') and immediately distinguishes the operation from related siblings by noting that an answered question is 'closed in the register, not deleted' (i.e., resolve_rfi vs delete_rfi). An agent can route correctly without opening any schema.

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

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

Explicitly states when to use ('a question you raised in error') and when not ('a question the architect answered is closed in the register'), effectively naming the alternative behavior. 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?

With no annotations, the description carries full burden. It does not disclose destructive nature beyond 'Remove', nor does it mention reversibility, permissions, or error behavior. The unrelated coordinate information does not contribute to behavioral transparency.

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

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

The first sentence is concise and effective, but the second sentence about coordinates is unrelated to the tool's parameters and adds noise, violating the 'every sentence earns its place' principle.

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?

Despite having an output schema, the description doesn't explain operation outcomes, idempotency, or side effects. The tool is simple but the description is incomplete and includes irrelevant coordinate context that distracts from core functionality.

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 description adds meaning to shape_id by specifying it is the id returned at commit time, which is not in the schema. However, the coordinate sentence is irrelevant and could confuse parameter expectations.

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?

Description clearly states the verb 'Remove', the resource 'committed shape', and the identifier 'id returned when it was committed'. It distinguishes from siblings like edit_shape by focusing on deletion of committed shapes.

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

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

No guidance on when to use this tool versus alternatives. The description provides no context about when deletion is appropriate, prerequisites, or exclusions relative to sibling tools like cut_out or edit_shape.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It states the operation is a mutation ('Journaled like every mutation'), reveals that it refuses human APPROVED seals, and explains that undo_last can re-seat a lifted mark. This is substantial and goes beyond the basic 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?

The description is three sentences with no filler. It front-loads the action, then packs in the essential details: source of the ID, restriction on human seals, and undo/redo behavior. Every sentence earns its place.

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

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

For a single-parameter tool with an output schema and no annotations, the description is remarkably complete. It covers purpose, valid ID sources, exclusivity of agent marks, the mutation/journaling behavior, and reversibility via undo_last. Nothing critical is missing for correct invocation.

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

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

The schema already fully documents verdict_id with the same source reference, but the description adds important semantic context by clarifying that only agent marks are valid and that human APPROVED seals are refused. This helps the agent understand which IDs are acceptable.

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: 'Lift an agent verdict mark by id', and immediately tells the reader where to find valid IDs ('mark_verdict's reply, or list_annotations verdicts[]'). This clearly distinguishes it from sibling tools like delete_shape or mark_verdict.

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 provides clear usage context: only agent verdict marks can be lifted, while the estimator's APPROVED seal is refused. It also mentions the undo_last journaling behavior, giving the reader practical when-to-use and what-to-expect guidance, though it does not explicitly name alternative tools for comparison.

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

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

With no annotations, the description carries the full burden and delivers: all-or-nothing refusal on unknown shape_id, negative lf, or openings meeting a full perimeter; the whole derivation is one undo step; deriving onto the source condition is refused; deducted openings are numerical not visible geometry. It also states where the claim is recorded (origin.derived).

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

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

Front-loaded with purpose and formula before constraints, and nearly every sentence earns its place by adding a rule or failure mode. It is dense and long, but for a tool with this many invariants the length is largely justified rather than 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?

Given an output schema exists, return-value explanation is not required, and the description covers everything else an agent needs: the derivation model, refusal conditions, undo granularity, and the condition-tag constraint. Nothing material for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: openings are the caller's own claim and are recorded, shape_id can be repeated to stack openings, and omitting openings yields gross perimeters. The stacking and claim-recording semantics are not obvious from the schema alone.

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

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

States a specific verb and resource — minting a wall base from committed rooms — and gives the exact formula (base LF = room perimeter − stated door openings). It also distinguishes itself from siblings by scoping to floor_area shapes of source_condition and naming measure_line for the alternative 'installed base' case.

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

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

Explicit when-to-use (derive base from committed rooms of source_condition), when-to-use-the-other (drawing of actual installed base → measure_line on physical runs), and the prerequisite workflow (look at doors with view_sheet, state openings per room). Alternatives and conditions are spelled out.

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

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

With no annotations provided, the description carries the full burden and goes far beyond it: it discloses all-or-nothing atomicity ('refuses the whole call before anything commits'), the single-undo-step behavior, the committed vs. withheld output split, coordinate system specifics (image px at scale 2.0, origin top-left, y down), and failure conditions. It also explains the critical geometric nuance that flood-traced rooms do not share edges, which materially affects what the tool 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?

The description is long, but every paragraph earns its place for a tool with complex geometric behavior. It opens with a one-sentence purpose, then systematically covers geometry, tuning, failure modes, and post-conditions. The structure uses clear signposts ('WHAT THE GEOMETRY ACTUALLY IS', 'Tuning:', 'All-or-nothing') to make the length navigable.

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 is remarkably complete for a complex tool, covering input semantics, output semantics (committed vs. withheld, total_lf), coordinate system, failure conditions, undo behavior, and recommended follow-up actions. Since an output schema exists, it doesn't need to enumerate return fields, but it still explains the meaning of those fields and the operational context, exceeding the minimum needed.

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 substantial meaning beyond the schema: it explains that condition is 'minted on first use', elaborates on max_gap_in's trade-off ('Wider only produces more wall_separated QUESTIONS, never more committed LF'), clarifies min_run_in as a corner artifact filter, and contextualizes condition_a/condition_b with examples. This is exactly the kind of semantic enrichment that helps an agent choose correct parameter values.

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

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

The description opens by naming the exact operation: 'Mint the transition where two finishes MEET (#202)', which is specific and action-oriented. It also distinguishes itself from siblings by explicitly calling out that it 'follows derive_base' and by referencing the 'symbol_sweep doctrine' to differentiate its behavior from symbol_sweep.

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 clearly establishes when to use this tool—after derive_base, when two finish tags require a transition—and gives practical tuning guidance ('raise it for thick walls'). It also directs users to alternatives for follow-up actions ('view_sheet at `at`, then measure_line or place_count the threshold yourself'), but it does not provide explicit 'when not to use' exclusions, so it falls short of a 5.

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

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

Despite no annotations, the description thoroughly discloses behavioral traits: the inheritance propagation rule ('change a coverage rate on the original and every twin that has not touched that row gets it'), the label uniqueness requirement with rationale (first match wins, duplicate tags cause unreachable conditions), refusal of duplicate labels, and reversibility. This far exceeds a simple 'duplicates a condition'.

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 lengthy but every sentence provides valuable information, covering concept, examples, constraints, and alternatives. It is logically structured, starting with core purpose and layering detail, with no redundant or filler content.

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

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

It addresses why the tool exists, the inheritance behavior, labeling pitfalls, what is not carried over ('No takeoffs come along'), and how to reverse the action. It also indicates the return value (condition_id) and is complemented by an output schema, making it complete for a complex 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?

While the schema defines 'label' and 'condition' with brief descriptions, the description adds critical semantics: label becomes a tag suffix with a concrete example ('CPT-1' + 'Level 2' → 'CPT-1 – Level 2') and must be unique. It also clarifies that condition is the finish tag the twin follows, providing much deeper meaning than the schema alone.

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

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

The description opens with 'Twin a condition — the same finish measured somewhere else, with its own supporting materials,' providing a specific verb and resource. It clearly distinguishes from siblings like split_condition, which ends inheritance, and edit_condition, which modifies a condition.

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

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

It gives a concrete scenario for when to use the tool ('One finish in two areas... same sheet goods over a slab and over a raised deck...') and explicitly names alternatives: 'Reversible with undo_last; use split_condition to end the inheritance permanently.' It also instructs the user to 'measure the new area against the returned condition_id,' guiding post-invocation steps.

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

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

No annotations are supplied, so the description carries the full burden and does so: it limits the blast radius (position, shape, dimension length, condition links, quantities and review records unchanged), explains the empty-string clearing behavior, states the RFI-link refusal, and confirms reversibility via one undo_last step. It also explicitly disclaims verdict or human-approval creation, heading off a likely confusion with mark_verdict.

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

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

Front-loads the core action, then layers scope limits, refusal condition, and undo semantics in short declarative sentences. No sentence is filler and no information is repeated.

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

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

An output schema exists, so return values need not be described. Combined with the disclosed side-effect scope, refusal rule, and undo path, an agent has everything needed to invoke this correctly and to recover from 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?

Schema description coverage is 100% and both parameters are documented in the schema itself, so the baseline is 3. The description's note that empty text clears the annotation largely restates the schema's 'empty string clears it' and adds no new syntax or format detail.

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 specific verbs (shorten, replace, clear) against a specific resource (text of an existing annotation), and explicitly scopes itself away from verdicts and from non-text properties. An agent can distinguish it from edit_condition, link_annotation, and mark_verdict 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?

Tells the agent where to source the id (list_annotations, not verdicts) and names an explicit when-not case: RFI-linked notes are refused and must be handled in the browser RFI register. That is both a precondition and a routing rule, not implied guidance.

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

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

With no annotations, the description fully carries the behavioral transparency burden. It discloses downstream effects (takeoff_summary emits waste-adjusted *_net quantities, exports carry both), error behavior on typo'd tags, roll_setup presence as opt-in with null opt-out, reply echoing figured orders, and undo_last reversing with a snapshot. No contradiction with structured data.

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

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

The description is long but every sentence carries value. It is front-loaded with the primary purpose, then elaborates on each parameter, edge cases, and interactions. Examples like 'carpet commonly 5–10' and issue references add specificity without 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?

It covers prerequisites, side effects, output behavior (reply echoes figured order), interaction with undo_last, and roll_setup nested options. Even with an output schema present, the description provides essential context about when and how quantities are applied, making it comprehensive for an agent.

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%, but the description adds significant semantic meaning: waste_pct is the estimator's cut-waste percentage (carpet 5-10), multiplier scales before waste, height_ft is the H knob measure_surface quantifies against, and roll_setup presence is opt-in with partial edits patching the existing setup. This goes far beyond the raw schema descriptions.

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

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

The description opens with 'Set a condition's quantity knobs' and enumerates the specific knobs (waste %, multiplier, height_ft, roll_setup), clearly identifying the resource and action. It also distinguishes from siblings like edit_materials by referencing its remove/patch rule and from measure tools by noting the default starting values.

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

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

It explicitly states when to use the tool: after measuring, to adjust quantity knobs that otherwise default to waste 0/multiplier 1, making takeoff net===gross. It also provides prerequisites (condition must resolve to an existing finish tag) and mentions alternatives like undo_last for reversal and contrasts with edit_materials add rule.

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

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

With no annotations, the description carries the full behavioral burden and does so: no review gate (direct edit), a 404 aborts the whole call before any write, referencing an id on a tag with no condition errors rather than silently minting, seam_lf reads 0 without a roll_setup, and undo_last restores the snapshotted materials array verbatim in one step.

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

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

It is front-loaded with the core action, but the ~250-word body includes an extended digression on seam geometry ('a 20-ft-wide room off a 12-ft roll seams once down its length...') that reads as documentation rather than crisp tool guidance. Informative sentences, but the volume costs discoverability/scannability.

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

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

An output schema exists, so return values need not be explained. For a 4-param mutation tool the description covers row semantics, the seam_lf edge case, seeding behavior, id resolution sources, error semantics, and undo — nothing an agent needs before calling it is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the row shape {name, per, basis, unit, round, note}, the quantity formula (basis total ÷ per, rounded up unless round:false), and the conceptual distinction that seam_lf is figured rather than measured. This goes beyond restating the schema's field docs.

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

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

The description opens with a specific verb+resource: 'Add, remove, or patch supporting-materials rows on a condition'. It defines what those rows are (coverage-rate lines that turn a measured quantity into an order quantity) and routes to siblings like edit_condition and takeoff_summary by name, so an agent can distinguish 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?

It states explicitly that 'add' alone can seed materials on a condition before anything is traced, that remove/patch consume existing row ids from this reply or export_takeoff, and that takeoff_summary strips materials for a compact reply. Alternatives (takeoff_summary, export_takeoff, edit_condition for roll_setup) and their selection conditions are named.

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

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

With no annotations, the description carries the full burden and does: it discloses that quantities are recomputed on every edit, that a role flip alone re-measures (closed area vs open length), that origin.reviewed shapes are rejected, that agent edits are tallied on origin.agent_edits, and the exact coordinate space (image px, scale 2.0, top-left origin, y down). This is exactly the behavioral context annotations would otherwise provide.

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

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

Purpose and the refusing-rule are front-loaded and every sentence carries operational content, but the 'ink vs pencil' metaphor and the density of the run-on middle sentence cost some clarity. Efficient overall, small flourish.

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?

A complex mutation tool with an output schema (so return values need no explanation) and full schema coverage; the description still fills the gaps that matter — recompute behavior, refusal conditions, edit accounting, and coordinate conventions. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning beyond the schema: it frames each parameter by consequence (verts move geometry, condition reassigns finish, role switches measurement mode, label is the per-room reporting seam) and explains the downstream effect of a role flip. It stops short of adding syntax details the schema already provides.

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

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

States a specific verb (REVISE) and resource (a committed shape), and explicitly distinguishes it from the delete-and-recreate path plus the sibling delete_shape. An agent can tell exactly what this does from the first clause.

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

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

Names the exact workflow loop — measure_polygon to commit, view_sheet overlay:true to inspect, then edit_shape to fix overshooting vertices — and states the boundary condition that reviewed (human-affirmed) shapes are refused. Usage and exclusions are both explicit.

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

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

With no annotations, the description carries the full behavioral burden and succeeds thoroughly. It discloses output geometry, layer naming, coordinate conventions, units, scale requirements, refusal behavior, handling of missing shapes, and overwrite semantics — far beyond what an annotation could capture.

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 purpose, and every sentence adds technical or behavioral value. It is dense and somewhat run-on, but for a CAD export tool with many edge cases, the length is justified. It could be tightened with clearer sentence breaks.

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

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

Given the tool's complexity, the description covers all essential operational concerns: output format, layer organization, coordinate system, units, scale prerequisite, multi-sheet selection, exclusions, overwrite safety, and a companion PDF tool. The presence of an output schema means return-value details are not needed 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?

Although schema coverage is 100%, the description adds meaningful meaning: path is required because DXF is a disk file aligned to the DWG; sheet is optional only when one calibrated sheet carries shapes; units affect INSUNITS; and overwrite has a nuanced 'your own previous exports already overwrite' behavior. This is more than baseline schema documentation.

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

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

The description states the tool exports the takeoff as a CAD drawing in DXF R2000 format, with native geometry rather than an image. It clearly distinguishes this from export_marked_pdf by emphasizing CAD interoperability and from export_report by noting that CAD areas match the report's areas.

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

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

It provides strong context: requires a calibrated sheet scale, requires a path, and explains when to pass the sheet parameter. It also names export_marked_pdf as a companion for a reviewed planset. However, it never explicitly states 'use this instead of X when Y' or lists exclusion conditions beyond the scale requirement.

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

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

With no annotations, the description carries the full burden and does so: it discloses the output structure, that unreviewed shapes are flagged on the last page, the default output path, that it needs no native canvas, and a specific refusal case (encrypted owner-password PDFs) with the reason and remedies. This is far beyond what structured fields provide.

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

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

Front-loaded with the core deliverable identity, then layers usage, review-path, default path, and refusal cases. It is dense and long but nearly every clause adds operational value; only minor tightening is possible.

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

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

An output schema exists, so return values need no explanation. The description covers behavior, refusal conditions, fallbacks, and the finish-the-takeoff workflow, leaving nothing an agent needs to call it correctly unstated.

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 in the schema (including default path and overwrite semantics). The description reinforces the default path but adds no syntax or meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (writes a PDF to disk) and resource (the MARKED-UP PLANSET deliverable), enumerating its contents: legend cover, per-condition totals, marked sheets. It explicitly distinguishes itself from siblings export_report ('carries the numbers for pricing; this carries the evidence') and export_dxf.

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

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

Gives explicit when-to-use ('finish EVERY takeoff by writing this file and giving the user its path') and names the contrasting alternative (export_report). It also states the review-path alternative for unreviewed machine-traced shapes (import_takeoff payload) and the fallback for encrypted plans (export from the app).

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

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

With no annotations, the description carries the full burden and does well: it describes what is computed, what is returned inline, and that passing path writes the document to disk. It omits practical traits such as output size/limits and does not explicitly label the operation as read-only against project state, but the mutation side effect (file write) is 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 resource identity, then contents, then sibling contrast, then workflow pairing, then return behavior. It is dense and long, and the 'A report alone is HALF the deliverable' framing is editorial, but nearly every sentence carries routing or payload information.

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

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

An output schema exists so return values need not be spelled out, yet the description still summarizes the document's shape. Combined with explicit sibling contrasts, workflow pairing, and file-write behavior, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: 'Returned inline; pass path to also write it to disk as JSON' clarifies the inline-vs-file duality that the schema's path description does not state on its own. project_name and overwrite semantics are 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 ('the computed Report document — "opentakeoff.report.v1"') and enumerates the payload contents (quantities with waste/multiplier, buy list, roll-up, base subtotals, scale provenance, annotations). It also explicitly distinguishes itself from two named siblings, export_takeoff and takeoff_summary, so an agent can route 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?

Gives an explicit decision rule: 'when the numbers are leaving for pricing, consume this,' contrasted against export_takeoff (raw config rows) and takeoff_summary (materials stripped). It further prescribes a companion workflow ('pair it with export_marked_pdf'), which is actionable routing guidance beyond mere context.

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

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

No annotations are provided, so the description carries the full burden, and it does well: it discloses that the payload is returned inline by default, that passing path additionally writes JSON to disk, and it documents the exact coordinate conventions (image px at scale 2.0, PDF pt × 2, top-left origin, y down) and that sheet payloads carry px and pt dims. It does not explicitly frame the operation as read-only versus file-writing in safety terms, which keeps it from a 5.

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

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

The definition is front-loaded with what the payload is, then adds invocation and coordinate details in compact clauses. Every sentence earns its place, though the dense coordinate-system sentence is somewhat tangential to tool selection.

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

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

An output schema exists, so return values need not be described, yet the description still explains the payload's identity and coordinate space. With 100% param coverage and no annotations, only the absence of explicit safety framing for the on-disk write leaves 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 description coverage is 100%, so baseline is 3, but the description adds real meaning: 'Returned inline; pass path to also write it to disk as JSON' clarifies that path is an additive side-effect flag rather than a mode selector, which the schema alone does not convey. The overwrite semantics are fully covered by the schema itself and not restated.

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

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

The description names a precise verb+resource — the full 'opentakeoff.takeoff_canvas.v1' annotations payload, exactly what the app autosaves and can re-import. This distinguishes it from the other export tools (export_dxf, export_report, export_marked_pdf) by making clear it is the native, round-trippable format. It stops short of explicitly naming those siblings, so 4 rather than 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?

The description implies usage ('Returned inline; pass path to also write it to disk as JSON') but gives no explicit when-to-use or when-not-to-use guidance relative to the other export siblings. The condition for writing to disk is clear, but routing between export tools is left to inference.

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

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

With no annotations, the description carries the full burden and delivers rich behavioral detail: continued schedules are one match with a parts list, rotated headers are flagged, building-specific tables carry a 'building' attribute, delta/REV-marked tables report revised_rows, errors include what was found, and the coordinate system is fully specified (image px at scale 2.0, origin top-left, y down). This gives the agent a clear mental model of edge cases and output structure.

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 a single, dense paragraph that front-loads the tool's purpose and then layers on critical edge-case behavior and coordinate conventions. Every sentence contributes useful information, though the length and lack of structural breaks (e.g., bullets) slightly reduce 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?

Given the complexity of schedule finding and the absence of annotations, the description covers purpose, return shape, edge cases (continuations, rotations, building, revised rows), error behavior, and coordinate system. An output schema exists, so return values need not be fully spelled out, but the description still provides sufficient context for correct invocation.

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

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

Schema description coverage is 100%, so the schema already defines the 'kind' parameter and its allowed values. The description repeats some of these values but omits 'equipment' (which is detailed in the schema), adding no meaningful semantics beyond what the schema provides. 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 (Locate) and resource (schedule table), and details exactly what is returned (sheet, title, headers, TOTAL row count, REGION). It distinguishes from siblings by positioning the output for subsequent view_sheet or read_sheet_text calls.

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 implies usage by saying results are 'sized for a view_sheet look or a read_sheet_text pull of exactly the table,' which suggests it's a preparatory step. However, it does not explicitly state when to use this tool versus alternatives like find_text or sweep_schedule_row, leaving the agent to infer the context.

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

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

No annotations are provided, so the description carries the full burden, and it does well: it discloses case-insensitivity, substring matching against pdf.js text runs, the room-label-split-across-runs caveat, the limit default of 200 and truncation/count behavior, and the coordinate system (image px, scale 2.0, PDF pt × 2, top-left origin, y down). It also flags that measure_polygon's One-Click is temporarily gated. Minor remaining gap: no explicit statement of auth/permission requirements or whether it mutates anything (though 'find' strongly implies read-only).

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

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

Front-loads purpose with the complement contrast first, then behavior, then the workflow, then coordinates. Sized appropriately for a tool with four parameters and non-obvious coordinate semantics, though it is dense and slightly long-winded in places (the room-label split example runs long).

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

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

Given the tool's complexity (nested region object, coordinate scale, truncation semantics) and that an output schema exists so return values need not be re-explained, the description covers everything an agent needs: what it finds, how matching works, how to scope, how the cap works, and the coordinate frame. 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 75%, high enough that the schema carries the heavy lifting (q, limit, region bounds all documented). The description still adds value: it clarifies the optional region syntax idea and the meaning of count/truncated in relation to limit, and reiterates the coordinate space. Not a full 5 because the region's numeric bounds are only in the schema, not elaborated in the description.

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

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

States a specific verb (LOCATE) and resource (a known string on a sheet), and explicitly positions it as the complement to the sibling read_sheet_text with a parenthetical contrast. An agent can immediately distinguish the two 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 explicit when-to-use (you already know the string and want its location), when-not (read_sheet_text returns what a region SAYS), and even the locate-then-trace workflow chaining into measure_polygon. 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?

With no annotations, the description carries the full burden and does so thoroughly: paging semantics (default 20000, ceiling 100000, ledger offset + returned + dropped === total, dropped recoverable via next_cursor), region intersection behavior with post-clamp echo and alignment to sheet_context's total_in_region, read-only and stateless operation, and refusal behavior for scans. It also specifies coordinate space and origin.

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 first sentence is front-loaded and clear, but the rest is a single massive paragraph dense with technical detail. While most sentences are informative, some repetition (e.g., 'undecimated') and lack of bullet-point structure reduce economy. It is adequate but could be more scannable for an agent.

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

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

Given the tool's complexity, the absence of annotations, and the presence of an output schema, the description is complete enough for an agent to call the tool correctly. It covers paging, region filtering, refusal cases, coordinate system, and output structure, leaving no critical gap for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema for the region parameter by explaining the exact keep test (intersects rect, endpoints untouched) and that total equals sheet_context's total_in_region, and clarifies the paging contract for limit/cursor. It does not add much for the sheet parameter, but the added region semantics lift it above baseline.

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

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

States a specific verb and resource: returns the sheet's raw vector stroke layer exactly as the engine sees it, and explicitly distinguishes itself from view_sheet, read_sheet_text, sheet_context, and shape verbs by naming what each does instead. The agent can identify this tool's unique output without opening any schema.

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

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

Explicitly names the sibling alternatives and their roles (view_sheet looks, read_sheet_text reads, sheet_context classifies a region) and states the use case: to run your own geometry against the app's raw extractor output. It also provides a when-not case: a scan has no strokes and the verb refuses, naming view_sheet as the path.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it does: merge identity rules, idempotency of re-import, this-session-calibration precedence, atomic refusal on scale mismatch, reviewed:false default for legacy traces, untouchability of imported reviewed shapes, unknown_files behavior, and undo_last semantics. This is rich, non-obvious behavioral disclosure beyond any structured field.

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

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

Front-loaded with confusing flavor text referencing a ticket '#151' and 'The way BACK IN', then one extremely dense run-on sentence packing many distinct behaviors. It is substantially overlong for a one-parameter tool and hard to parse, though the content is nearly all relevant, so not a 1.

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

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

Complete enough: since an output schema exists, it needn't explain return values, and it still correctly mentions the reply's unknown_files field. Covers prerequisites, merge semantics, refusal behavior, and downstream effects (undo_last, approval marks). Minor gap: it doesn't plainly restate what the required 'path' refers to at the top.

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 parameter is already documented in the schema, so baseline is 3. The description adds meaning by specifying the file format/version ('opentakeoff.takeoff_canvas.v1') and that a prior export_takeoff or app save is acceptable, which clarifies what path should point to beyond the schema's generic 'JSON file'.

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 (load/import) and resource (an opentakeoff.takeoff_canvas.v1 file), and explicitly distinguishes itself from export_takeoff (its counterpart) and from list_shapes/takeoff_summary which are named as audit alternatives. The merge-rule detail makes the tool's exact role unambiguous.

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

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

Gives explicit when-to-use scenarios (resume yesterday's work, extend a human-reviewed takeoff, audit someone else's export) and names the alternative tools for the audit case (list_shapes/takeoff_summary). It also states a prerequisite ('Requires a loaded plan') and remediation paths (align scales and re-export, or use a fresh session) for refusal.

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

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

No annotations provided, so description carries burden. Discloses key behavior: detaching via empty string and tag minting on first use. Could mention more side effects, but adequate.

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

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

Three sentences, front-loaded with primary function, followed by use cases and a behavioral note. No redundant information.

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

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

Given tool simplicity and existence of output schema, description covers purpose, usage, and key behavior. Does not address errors or edge cases, but sufficient for typical use.

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% with clear parameter descriptions. Description adds extra context: 'list_annotations' for IDs and tag minting, enhancing meaning beyond 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 the verb 'attach' or 'detach' and the resource 'annotation' and 'condition', clearly distinguishing from siblings like 'annotate' and 'list_annotations' by referencing them. It explains primary function and use cases.

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 cases: tie up unattached notes or move annotations to correct conditions. References sibling 'list_annotations' for context. Does not list when not to use, but guidance is sufficient.

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

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

With no annotations provided, the description fully discloses critical behavior: coordinate transformation (image px at render scale 2.0, PDF pt × 2, origin top-left, y down), resolution of condition_id to finish tags, and the semantics of 'unattached' and 'verdicts'. This goes far beyond basic expectations.

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

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

The description is dense but every sentence carries necessary behavioral detail. It efficiently covers output fields, filters, and coordinate system without redundancy. Slightly long, but the complexity of information justifies the length.

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

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

For a tool with no annotations and complex output behavior, the description covers all essential aspects: filters, coordinate system, resolved condition semantics, and the purpose of special fields. An output schema exists, so not explaining every return field is acceptable; the description still adds enough context to use the tool correctly.

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

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

Schema descriptions already cover both parameters (100% coverage). The description adds meaning by clarifying that filters can be combined ('or both'), and explicitly maps the 'condition' parameter to the resolved finish tag concept, which is not fully apparent from the schema alone.

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

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

The description clearly states the tool lists every annotation on the takeoff with condition_id resolved to its finish tag. It distinguishes itself from siblings by mentioning resolved conditions, unattached counts, and verdicts, which positions it as the comprehensive annotation inventory tool.

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 explains filtering by sheet, condition, or both, and ties output fields to concrete actions: 'unattached' identifies candidates for link_annotation, and 'verdicts' serves the mark_verdict/delete_verdict family. This provides clear when-to-use guidance versus related tools.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the returned fields, the meaning of withdrawn[] (tombstoned by delete_rfi), and the pending-acceptance state of agent-raised RFIs. It does not state read-only/authorization behavior explicitly, but the rich semantic disclosure is strong.

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

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

It is front-loaded and every clause carries information, but it is a single dense sentence with multiple em dashes and parenthetical asides. The lack of sentence breaks makes it harder to parse than necessary, and some return-field detail is redundant with the output schema.

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

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

Given a zero-parameter tool with an output schema and no annotations, the description supplies the semantic context an agent needs: what an RFI listing contains, what the withdrawn[] gap means, and when to consult it before creating a new RFI. 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?

The tool has zero input parameters, so there is no parameter semantics to explain; the empty schema's 100% coverage makes the baseline 4. The description appropriately does not invent parameter guidance.

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 pairing: listing every RFI in the register with explicitly enumerated attributes. It distinguishes the tool from siblings like create_rfi and delete_rfi by scoping it as the read-before-you-raise view and by explaining that delete_rfi tombstones entries.

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 trigger — 'Read this before raising a question the register already holds' — which routes the agent away from create_rfi when the register may already contain the answer. It does not name any explicit exclusion or alternative beyond that implication, so it falls short of full when/when-not guidance.

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

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

With no annotations, the description carries the behavioral burden and does disclose the key traits: read scope is limited to 'committed' shapes, filters only narrow (never broaden), and an empty result is normal rather than a failure. It does not cover auth/permission needs or pagination limits, which would be relevant for a large inventory read.

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

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

Front-loaded with the core purpose and field list, and the operational caveats come last. It is a single dense sentence with some incidental noise (the '#149' issue reference) but each clause largely earns its place.

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

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

For a two-param, optional-filter read whose output schema already defines the return payload, the description covers scope, filter behavior, and empty-result handling completely. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented (sheet = 'Only shapes on this sheet', condition = 'Only shapes under this finish tag'). The description adds only the semantic that filters narrow rather than expand, which is useful but minimal 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+resource ('shape inventory') and enumerates the exact fields returned (id, sheet, condition tag, role, quantities, room label, vertex count, review state). It explicitly distinguishes itself from sibling export_takeoff and positions itself as the id source that edit_shape and delete_shape require.

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

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

Names the alternative it replaces ('without pulling the whole export_takeoff payload'), states the filtering options (sheet, condition, or both), and clarifies result semantics ('filters narrow, an empty list is a result, not an error'). An agent knows exactly when to reach for this vs. the bulk export.

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

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

With no annotations provided, the description carries the full burden and excels: it discloses the destructive default (clears session), the merge behavior, the refusal condition, the return payload, coordinate system details, and the conversion to browsable resources. This is a comprehensive safety/behavioral profile.

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 a single dense paragraph but logically organized: action, default behavior, merge variant, edge case, return values, resources, and coordinate system. Every sentence adds necessary information with no filler, achieving conciseness through purposeful density.

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

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

Given the tool's moderate complexity and absence of annotations, the description covers everything an agent needs: the two modes, re-load restriction, return fields, coordinate transformation, and resource availability. It is fully sufficient for correct invocation and interpretation.

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 schema already documents both parameters with 100% coverage, so the baseline is 3. The description adds meaningful context beyond the schema by elaborating on the default behavior, the meaning of merge:true, and the edge case of merging into an empty session, increasing clarity for parameter usage.

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

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

The description opens with a clear verb+resource ('Open a plan PDF from disk') and immediately clarifies the default replacement behavior versus merge mode. This distinguishes it from sibling tools that operate on already-loaded sheets or produce analyses.

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 contrasts the default replace-all behavior with merge:true for adding to a working set, explains the bid-set use case, and states that re-loading an already-merged file is refused. This gives clear when-to-use and when-not-to-use guidance, including a concrete scenario.

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

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

With no annotations, the description carries full responsibility for behavioral disclosure. It details side effects (provenance recording, glyph anchor persists even if shape deleted), non-effects (touches no quantity, gates nothing), rendering behavior, tally in marked-set, payload propagation, and coordinate conventions. It also explains the one-mark-per-shape rule and interaction with undo_last. This is exemplary transparency.

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

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

The description is long but every sentence contributes unique, essential information. It is front-loaded with purpose, then systematically covers targeting, behavior, rendering, and coordinates. No filler or repetition; efficient for the tool's complexity.

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

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

Given the tool's moderate complexity, the description is remarkably complete. It covers all parameters, behavioral nuances, sibling relationships, coordinate systems, and lifecycle interactions (re-mark, undo, list). The output schema exists, so not describing return values is acceptable. There are no significant gaps.

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

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

Although schema coverage is 100%, the description adds substantial meaning beyond the schema. It clarifies the mutually exclusive targeting modes (shape_id vs sheet+at), the coordinate system (image px at render scale 2.0, top-left origin, y down), and the exact role of text. This significantly enriches parameter understanding.

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

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

The description opens with a clear, specific verb+resource ('Mark the agent's VERDICT on work') and immediately distinguishes this tool from the estimator's approval ring, identifying it as the only half an agent can mint. It explicitly states what the tool does and how it differs from siblings like delete_verdict and annotate.

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 provides explicit when-to-use guidance: it distinguishes the two targeting modes (shape_id vs sheet+at) and states 'Exactly one target.' It also mentions alternatives such as delete_verdict for re-marking and list_annotations for inventory, and clarifies that this is the agent's tool distinct from the estimator's approval. This exceeds basic usage guidance.

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

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

With no annotations, the description carries the burden and does well: it discloses the scale prerequisite, that condition commits the trace as a persistent linear shape, that arc_through bakes arcs on commit, and precisely defines the coordinate space (render scale 2.0, pt×2, origin top-left, y down). It does not state permissions, rate limits, or exactly what a non-committing call returns, 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?

Front-loaded with the core action and unit, followed by prerequisites, commit behavior, curved-run handling, and the coordinate frame. Every sentence carries information, though the coordinate-space sentence is dense and could be tightened.

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

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

An output schema exists, so return values need not be explained. The description covers the scale precondition, commit semantics, arc behavior, and the drawing coordinate system — enough to call it correctly. Missing only edge behavior for a measure-only (no condition) call and any mutation/permission caveats.

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

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

Schema coverage is only 25%, so the description must compensate, and it largely does: it explains pts (min 2 image-px points and the coordinate frame), condition (commit semantics with example categories base/transitions/feature strips), and arc_through (one point on the bow, marked). Only 'sheet' is left undocumented, so the added meaning is substantial despite the coverage gap.

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

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

States a specific verb and resource ('Measure an open polyline'), the minimum input, and the output unit ('length_lf at the sheet's scale'). The 'open polyline'/'linear shape' framing implicitly separates it from measure_polygon/measure_surface, but no sibling is named explicitly, so it stops short of full 5-level differentiation.

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

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

Gives clear context and a precondition: 'Requires the scale to be set', plus the conditional rule that condition commits it as a linear shape and arc_through is used for curved runs. It lacks an explicit 'when not to use this / use measure_polygon instead' exclusion, so it is clear context rather than 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?

With no annotations, the description carries the full burden and does well: it discloses the scale prerequisite, that condition commits vs a bare measurement, that role 'deduct' subtracts, and that arcs are baked to vertices on commit with origin.curved stamped. It does not cover failure handling beyond the arc refusal note (which lives in the schema) or idempotency, so it is strong but not exhaustive.

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

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

Front-loads purpose and units before the tracing guidance, and every clause is task-relevant for a takeoff tool. It is dense and long - the room-ring and curved-wall paragraphs could be tighter - but nothing 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?

Complete for a complex geometry tool: coordinate convention (image px, render scale 2.0, origin top-left, y down), units in both px and pt, prerequisites, arc semantics, and a verify-then-fix workflow. An output schema exists, so return values need not be restated.

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

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

Schema coverage is only 20%, so the description must compensate and largely does: it explains verts (min 3, image px), role ('deduct' subtracts, default floor_area), condition (commit), and the arc_through curved-wall pattern including where to place the point. Only 'sheet' is left to inference, which is low risk given the surrounding 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?

Names a specific verb and resource (measure a closed polygon you supply) and states the concrete outputs (area_sf and perimeter_lf at the sheet's scale). This clearly separates it from measure_line and measure_surface without needing to open any schema.

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

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

Gives real usage context: state must be set first, pass condition to commit, use role 'deduct' to subtract, verify with view_sheet overlay:true and fix with edit_shape. It stops short of naming measure_line/measure_surface as the alternatives for non-polygon work, so selection vs those siblings is left implicit.

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

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

With no annotations, the description carries the full burden and delivers unusual detail: the refusal-on-missing-height behavior, the separate undo journal entry for height_ft, the height snapshot on the committed shape, and the arc baking to ordinary vertices with origin.curved stamped. It does not cover permissions/auth, and output schema covers returns, so the safety profile is thin but the mutation semantics are well 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 quantity identity and use case, then the prerequisites and coordinate convention. It is dense and long, with some clause-heavy sentences, but nearly every sentence adds operative information rather than restating the name.

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

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

For a mutation tool with no annotations, the description covers the failure mode, the side effect on the condition, undo journaling, scaling requirements, and the coordinate space; with an output schema present, return values need not be explained. Nothing an agent needs to invoke it correctly appears to be missing.

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

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

Schema coverage is 80%, so the baseline would be 3, but the description adds real meaning beyond the schema: the coordinate system (image px at render scale 2.0 = PDF pt × 2, origin top-left, y down), arc_through's Curve-mode behavior and its refuse cases, and the ordering effect of height_ft on the condition. These are semantics the schema strings do not convey.

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

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

States a specific verb and resource ('Surface Area — wall SF: trace an OPEN run along the wall in plan view') and contrasts it with the sibling it cannot replace ('the quantity family measure_polygon cannot produce'). An agent can distinguish it from measure_line and measure_polygon without opening the schema.

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

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

Explicitly names the use cases (wall tile, wainscot, wall systems) and the alternative (measure_polygon), and spells out the preconditions: height must come from height_ft or edit_condition, 'with neither, this refuses and mints nothing', plus the sheet scale requirement. Both the when and the when-not are stated.

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

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

With no annotations, the description does real work: it discloses atomic undo ('the whole call is ONE undo step'), that each point yields a computed {count: 1} shape, that no scale is required, and how takeoff_summary will report the result. Auth/permission needs are not covered, but the behavioral payload is substantial.

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

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

Opens with the core verb and unit, then packs in coordinate, undo, and reporting detail. Dense but front-loaded and each sentence carries information; slightly rambling with parenthetical asides.

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-required-param mutation with an output schema (so returns needn't be explained), the description covers coordinate space, atomicity, condition minting, and downstream reporting. Nothing critical is missing, though permission/error behavior is 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 67% and the description adds meaning beyond it: it defines the coordinate space precisely (image px at render scale 2.0, PDF pt × 2, origin top-left, y down) and notes the condition tag is minted on first use. This meaningfully supplements the points/condition schema entries.

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 ('Count markers', committing one count shape per point) and clarifies it is the scale-free EA quantity family. It does not explicitly name or differentiate from the sibling count_marks or symbol_sweep, so the reader must infer the boundary.

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

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

The examples (thresholds, stair nosings, floor boxes, entrance mats) and 'NO scale required' imply the right context for scale-free counting, but there is no explicit when-to-use vs count_marks/symbol_sweep guidance or exclusion.

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

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

With no annotations, the description carries the full burden and delivers: the diff is held PENDING until accepted, nothing changes until then, takeoff_summary and export_report keep computing current values and carry the diff as proposed_condition_edits, and acceptance is byte-for-byte identical to a direct edit_condition. It also discloses four distinct refusal/failure modes (no-op proposal, tag collision, one-pending-diff-replaces-earlier, required rationale), which is unusually complete for a mutation tool with zero annotation coverage.

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

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

Purpose and the edit_condition contrast are front-loaded, and each clause carries real information (pending semantics, refusals, replacement rule). It is on the dense/long side with several parentheticals and em-dash asides, so it is efficient rather than maximally tight.

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

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

An output schema exists, so return values need not be described, and the description still covers pending state, the side-channel field (proposed_condition_edits), the acceptance write path, refusal conditions, and one-pending-diff/undo behavior. Nothing an agent needs to call this correctly or predict its effects 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 57%, so the description should compensate. It does list the meaningful parameter set (finish tag, waste %, multiplier, height_ft, roll_setup) and adds a semantic constraint the schema lacks: 'Only fields that differ from the current value are recorded.' Rationale's meaning is elaborated ('Why — the schedule row, the spec section, the sheet note that decided it') matching the schema description, and finish_tag is flagged as a rename. It stops short of per-field units/format detail but covers the semantics well.

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 ('PROPOSE a change to a condition instead of making it') and immediately contrasts it with the sibling edit_condition, so an agent can distinguish the two tools without opening a schema. The parenthetical lists the exact field classes the proposal can carry (tag rename, waste %, ×N multiplier, height_ft, roll_setup).

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

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

Explicitly routes: edit_condition is 'the wrong power for "I think this condition is wrong"', and the reason a proposal should instead be a decision the estimator makes is spelled out. It also names undo_last as the recovery path and withdraw_condition_edit exists as a sibling, giving clear when/when-not framing.

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

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

With no annotations, the description carries the full burden and does so well: it states nothing commits geometry or changes a total, an empty proposal is just a heading, attached verbs (measure_polygon, measure_line, etc.) bind to it until superseded, and accepted shapes leave the batch. It also points to takeoff_summary for ledger state — rich behavioral context 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?

Front-loaded with the purpose and the key constraint ('nothing here commits geometry'), and every clause is informative. It is on the long side and the label/rationale explanation partly repeats the schema descriptions, costing it a point.

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

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

An output schema exists, so return values need no explanation, yet the description still usefully points to takeoff_summary for the pending/accepted/withdrawn ledger. For a two-required-param creation tool with no annotations, the coverage of intent, timing, and side effects is 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%, and the parameter descriptions in the schema are nearly verbatim what the description says (label = what the estimator reads on the pill; rationale = what decided the batch). The description adds framing (neither is a comment) but little syntactic or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Open a PROPOSAL — a named batch of the shapes you are about to commit') and gives it a concrete identity concept (#365). It explicitly distinguishes itself from revise_proposal (replaces) and withdraw_proposal (removes), so an agent can route correctly without opening other schemas.

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

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

Gives explicit timing ('Use it BEFORE the work') and a vivid workflow analogy for the estimator. It names the alternatives by function — revise_proposal replaces the batch, withdraw_proposal removes it — and notes that already-accepted shapes are out of scope, covering when-not as well as when.

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?

Since no annotations are provided, the description fully carries the transparency burden. It discloses the coordinate system (image px, origin top-left, y down, render scale 2.0), explains the return format, and notes how sheet payloads carry dimensions in both px and pt. No behavioral surprises are left unmentioned.

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 five sentences long, front-loaded with the core functionality ('The sheet's text with positions'), followed by optional behavior, use cases, coordinate details, and dims note. Every sentence adds value without redundancy or verbosity.

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

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

Given the tool's moderate complexity (2 params, one nested) and the presence of an output schema (so return values need not be reiterated), the description covers all essential aspects: purpose, parameter formats, coordinate system, and typical use cases. It is sufficiently complete for an agent to invoke 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?

The input schema has 2 parameters (sheet, region) with 0% description coverage, so the description must compensate. It explains the optional region parameter's format and coordinate significance, and it clarifies coordinate space for region values. The 'sheet' parameter is not elaborated, but its purpose is inferable from context. The description adds meaningful value beyond the raw 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 clearly states the tool reads sheet text with positions, including the structure '[{str, x, y}]' and joined text. It provides concrete use cases (title blocks, room labels, etc.) and distinguishes itself from sibling tools like 'sheet_info' (metadata) or 'measure_*' (measurements), making the purpose unambiguous.

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 'Use it to read title blocks, room labels, finish schedules, and scale notes,' giving clear guidance on when to apply the tool. However, it does not explicitly state when not to use it or contrast with siblings, though the context of siblings (delete, measure, etc.) makes the use case distinct.

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

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

With no annotations, the description carries the full burden and does so richly: it discloses the resulting status (answered), the date-stamping behavior, the added ISO timestamp, and the refusal semantics for non-open records. This is exactly the state-machine and side-effect information an agent needs for a mutation with zero annotation coverage.

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

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

Front-loaded with the core action and state constraint, then progressively adds refusal rules and the undo escape hatch. The parentheticals are dense but each carries real information; nothing is pure filler, though it is on the longer side for two 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?

An output schema exists so return values need no explanation, and the description still covers preconditions, refusal behavior, timestamp effects, and reversal. Nothing 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 the schema already documents both parameters (baseline 3). The description adds semantic guidance beyond the schema for the answer param — "Record the answer the drawings or the architect actually gave; an RFI is not resolved by guessing" — clarifying what a valid answer is.

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

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

Opens with a specific verb+resource: "Answer an OPEN RFI." It immediately distinguishes itself from the create_rfi/list_rfis/delete_rfi siblings by naming the exact state transition (open -> answered) it performs.

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 states the precondition ("Only an open RFI resolves") and the exclusion ("an answered, closed, or void one is refused rather than re-answered"). It also names the alternative for reversing a mistake ("undo_last reverses your own resolve"), giving the agent a clear 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?

With no annotations to fall back on, the description thoroughly discloses behavioral traits: refusal over guessing, 'unresolved' status on ambiguity, handling of reused numbers, building-qualified tags, delta/REV tags and their effect (post-revision answer), and the image coordinate system (px at render scale 2.0, top-left origin, y down). This is far beyond what annotations would provide.

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

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

The description is a single dense paragraph, but logically ordered: from plan tag to schedule rows to finish codes, then evidence and edge cases. Each sentence adds necessary information. It is long but appropriately packed with essential behavior for a complex tool.

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

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

Given the tool's complexity (multi-step resolution, continuation sheets, ambiguity handling, building-qualified tags, revision markers, coordinate system), the description covers all crucial context. It explains edge cases, coordinate details, and the link to view_sheet. The existing output schema handles return values, so the description is complete for selection and invocation.

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

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

The single parameter 'tag' is fully described in the schema (including examples and building-qualified syntax). The description adds little beyond restating the schema's parameter description, though it does reinforce the resolution context. Since schema coverage is 100%, 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 clearly identifies the tool's action: resolving a single room tag across the entire set, tracing through schedule rows and finish definitions, and outputting evidence pointers. It distinguishes itself from sibling tools like sweep or find_text by specifying the multi-step resolution chain, making its purpose unambiguous.

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 provides strong contextual guidance: it explains when to use the tool (to resolve a room tag end-to-end), how to handle multi-building sets, and that view_sheet should be used to inspect evidence. While it doesn't explicitly name alternative tools for non-resolution tasks, it implicitly distinguishes itself by describing a unique workflow, and the mention of view_sheet for evidence checking gives practical usage direction.

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

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

With no annotations, the description carries the full burden and delivers: atomic all-or-nothing validation before any removal, the exact validation checks (sheet, scale, vertex count, height for surface_area), error reporting ('which entry and why'), undo_last restoring the prior batch exactly, and that accepted shapes are untouched. This is unusually complete behavioral 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 core action is front-loaded in the first clause, and nearly every sentence earns its place. It is dense and long with stacked parentheticals, which slightly hurts scannability but not correctness.

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

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

An output schema exists so return values need no explanation, and the description fully covers the mutation's transactional semantics, validation rules, coordinate space, and role constraints. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 50%, so the description must compensate and does: it specifies verts are image px, role minimums per role type (floor_area/deduct >=3, linear/surface_area >=2, count 1), and the coordinate convention (scale 2.0, pt x 2, origin top-left, y down). This adds real meaning beyond the schema, though proposal_id is only lightly addressed.

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