AssetLab

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: partial-failure semantics ('one failure does not affect others'), per-item return results, the {resource}:write scope requirement, and the rate-limit accounting (1 request). It stops short of stating the failure response shape (e.g. whether the call returns 207 vs 400) or idempotency behavior.

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

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

Five short, front-loaded sentences; the limit, the partial-failure guarantee, and the rate-limit note are each distinct and none restate the tool name. Nothing is padded.

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

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

For a 2-parameter batch tool with no output schema, the description supplies the operational facts an agent needs (cap, isolation of failures, per-item results, scope, rate-limit cost). Only a note on error/response shape or retry behavior 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% and both parameters are documented in the schema, including the maxItems=100 bound that the description merely repeats. The only added meaning is tying the 'write scope' requirement to the resource parameter, 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 ('Create') plus a clearly bounded resource scope ('multiple records of a resource type in one API call'), which cleanly separates it from the ~90 singular create_* siblings and from bulk_update. An agent can tell what it does 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?

Usage is implied by the batch semantics and the max-100 cap, but the description never explicitly names the alternative (e.g. 'use create_asset for a single record, bulk_create for batches') or states when a batch is preferable to repeated single calls. It also gives no exclusion guidance for bulk_update.

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 100-item cap, per-item independence ('one failure does not affect others'), per-item results, required {resource}:write scope, and rate-limit accounting. It omits reversibility and what a failed-item result contains, but this is substantially more behavioral context than most definitions.

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

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

Five short sentences, zero waste, front-loaded with the core action and cap. Each sentence delivers a distinct operational fact (cap, id requirement, independence, scope, rate limit).

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

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

For a 2-parameter batch mutation with no output schema, the description covers limits, failure semantics, scope, and return shape adequately. Only edge details (e.g., behavior on missing/invalid IDs beyond independence) are unaddressed.

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

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

Schema description coverage is 100%, so the schema already documents both parameters, including the 'id' field requirement. The description adds the {resource}:write scope mapping, which is mildly useful, but otherwise repeats schema content; 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 ('Update multiple records of a resource type in one API call') with a clear batch scope. The batching semantics distinguish it cleanly from the many single-record update_* siblings and from bulk_create.

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 its use case (bulk efficiency, max 100 items) but never states when to prefer this over the singular update_* tools or when to fall back to them. Usage is inferable rather than 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?

No annotations are provided, so the description carries the full burden. It usefully discloses the required 'assets:write' scope, but says nothing about validation behavior, whether the child IDs must all be supplied, error handling, or what the create returns.

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

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

Front-loads purpose, then scope, then the two resolution workflows. Dense but each sentence carries information; only the two hierarchy walkthroughs sit close to redundant with the per-parameter hints in the schema.

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

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

For a 38-parameter creation tool with no annotations and no output schema, the description supplies purpose, authorization scope, and the two dependency-resolution chains that an agent would otherwise get wrong. It stops short of describing required-vs-optional expectations or post-create behavior, but covers the critical trap (hierarchy resolution order).

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

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

Schema description coverage is 100%, so the schema already documents all 38 parameters, including the same 'resolve first via list_sites' hints reproduced in the description. The description adds the enforced ordering of lookups, which is modest incremental value over the schema. 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?

States a specific verb+resource ('Create a new asset'), so the operation is unambiguous. However, with dozens of create_* siblings including create_infrastructure_asset, create_asset_betterment and create_asset_type, it does nothing to distinguish itself from those neighbors.

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 useful workflow guidance for resolving the location and system hierarchies (list_sites → list_buildings → list_locations and list_system_classes → list_system_groups → list_systems), which is more about parameter preparation than when to select this tool. There is no explicit when-to-use vs the other create_* variants.

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 the description carries the full burden and does it well: it discloses the rejection rule (work adding neither amount nor life), the re-basing of net book value and remaining life from occurred_on, that purchase_date is NEVER changed, and the required asset_betterments:write scope. These are non-obvious side effects an agent must know.

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

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

Front-loads the core purpose and the required/at-least-one constraint before the side-effect and alternative-tool guidance. Dense but every clause adds functional information; slightly long, though nothing is wasted.

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

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

For a mutation tool with no annotations and no output schema, the description covers requirements, rejection behavior, side effects on derived fields, scope/auth needs, and alternative-tool routing, leaving nothing an agent needs to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds the cross-parameter constraint (at least one of capitalized_amount or added_life_years, otherwise rejected) and clarifies that occurred_on is the in-service date, not the invoice date, which goes beyond the schema's per-field text.

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 ('Record capital work that ALREADY extended a facility asset's life') and gives concrete examples (elevator modernization, boiler retube). It explicitly distinguishes itself from sibling tools create_asset_lifecycle_event and condition assessments.

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: 'Use asset_lifecycle_events for work expected in future; use a condition assessment for what someone observed,' instructs to call list_assets first to resolve asset_id, and covers the in-service-date misconception case. Clear when-to-use and when-not-to-use.

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 it does disclose a genuine operational requirement: the asset_comments:write scope. However, it says nothing about the mutation's nature, whether the comment can be edited/deleted afterward, or what the call returns, leaving meaningful behavioral gaps for a write operation.

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

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

Two short sentences, front-loaded with the action and followed by the permission requirement. Nothing is wasted and no filler is present.

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 simple two-parameter create tool, the description covers purpose and authorization, which is roughly adequate. It omits any sense of the response or failure behavior, and with no output schema and no annotations there is no other structured source to fill that gap.

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

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

Schema description coverage is 100% with only two parameters, both documented in the schema (comment text, asset UUID). The description adds no parameter-level detail beyond that, 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?

The description states a specific verb and resource ('Create a new comment on an asset'), which is unambiguous and distinguishes it from the many sibling comment creators (project, work order, infrastructure asset) by naming the asset scope. It stops short of explicitly naming or contrasting those siblings, so it is clear but not maximally differentiating.

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

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

There is no guidance on when to use this tool versus alternatives such as update_asset_comment, list_asset_comments, or the other comment-creation tools. The agent is left to infer usage entirely from the tool name.

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 it does disclose the auth scope requirement plus a workflow prerequisite. However, it omits key traits: that this is an append-only point-in-time record, whether duplicates are permitted, and what the call returns. The potentially destructive purchase-cost overwrite behavior is documented only inside the schema, not surfaced in the description.

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

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

Three short sentences, zero filler, with the core action stated first and the prerequisites following. 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 create tool with a fully documented 9-parameter schema and no output schema, the description covers the essentials: what it creates, the scope needed, and the prerequisite lookup. It could add what happens on success or how the assessment relates to downstream FCI/score calculations, but nothing needed 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 description coverage is 100%, so the schema already explains every parameter, including the detailed caveats around update_purchase_cost. The description adds only the list_assets resolution hint for asset_id, which is a marginal gain over the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Record a point-in-time condition assessment against an asset'), which is far more precise than the many terse sibling names like create_asset_cost or create_asset_status. It does not explicitly distinguish itself from update_asset_condition_assessment or delete_asset_condition_assessment, but the create semantics plus 'point-in-time' framing make the intent clear.

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

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

Gives two concrete operational prerequisites: the required write scope and the instruction to 'Call list_assets first to resolve asset_id.' That is genuine when/how guidance. It stops short of stating when NOT to use it (e.g., correcting an existing assessment should go through update_asset_condition_assessment).

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

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

With no annotations, the description carries the full burden, and it does disclose the required write scope, which is genuinely useful. However, for a mutation it says nothing about reversibility, validation, or the cross-entity side effect (costs consuming a purchase order's remaining balance) that only appears buried in the schema for purchase_order_id.

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

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

Two short clauses with the operation and scope front-loaded, no filler. It is slightly terse for an 11-parameter mutation, but nothing is wasted.

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

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

For a mutation with 11 params, no annotations, and no output schema, the description covers purpose and auth but omits what the call returns, what gets counted against PO balances, and when a sibling create tool is the better choice. Adequate but with clear gaps.

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters including the meaningful purchase_order_id balance semantics. The description adds no parameter-level information, so the baseline of 3 applies.

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

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

States a specific verb (Create) and resource (asset cost entry) and adds a disambiguating anchor — 'the record type shown on the AssetLab "Expenses" page' — which helps separate it from the sibling create_expense and create_infrastructure_asset_cost. It does not explicitly name those siblings, so a reader must still 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?

No when-to-use, when-not-to-use, or alternative tool is named, even though create_expense, create_infrastructure_asset_cost, and create_purchase_order_line all overlap. The only contextual guidance is 'Requires asset_costs:write scope,' which is a prerequisite rather than usage selection 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 behavioral burden. It does disclose the required scope (asset_documents:write) and the upload-before-create sequencing, which is genuinely useful. It does not say whether the call is idempotent, what happens on duplicate file_path, or what is returned, leaving gaps 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?

Two short sentences, front-loaded with the action and followed by the prerequisite and scope. No filler. It could be marginally tighter but nothing is wasted.

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

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

For an 8-parameter mutation tool with no annotations and no output schema, the description covers the essential workflow (upload first) and authorization requirement, but omits return behavior, failure modes, and how this differs from the parallel document-creation tools.

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% across all 8 parameters, so the schema already documents name, asset_id, category enum, file_size, file_type, etc. The description only reinforces the file_path linkage to create_upload_url. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Create an asset document record') and adds the precondition that the file must already be uploaded. It does not explicitly differentiate itself from the many sibling create_*_document tools (project, contract, infrastructure asset), but the resource is unambiguous from the name plus description.

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

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

Gives a concrete ordering rule: create the document only after obtaining a path via create_upload_url. That is real usage guidance. It stops short of naming alternatives (e.g. create_infrastructure_asset_document) or stating when this tool should not be used.

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

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

No annotations are provided, so the description carries the full burden, and it delivers: it discloses the required auth scope (asset_lifecycle_events:write), the exactly-one-of-two scope-id constraint with type-before-group resolution precedence, and the semantics of what does NOT belong here. It stops short of describing failure behavior or what the create returns, which leaves a modest gap for a 17-parameter mutation.

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

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

Front-loaded with the core purpose, then the scope rule, then the exclusion, then the prerequisite lookups. Dense and every sentence earns its place, though the four-clause opening block is packed tightly enough to require careful reading.

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 17-parameter, 4-required mutation with no annotations and no output schema, the description covers purpose, scoping semantics, prerequisites, and auth requirements, while the schema fully documents parameters. Adequate to call correctly; only return/failure expectations are unaddressed.

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

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

Schema description coverage is already 100%, so the baseline is 3. The description adds genuine value beyond the schema by explaining scope resolution precedence (an asset resolves its type's own strategy first, else its type group's) and the conceptual role of event_class relative to replacement, which the schema does 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+resource ("Create a facility lifecycle strategy event") and immediately disambiguates it from its infrastructure sibling and from the replacement-forecast concept. It also explains the scope model (asset-type scope, never individual assets), so an agent can tell it apart from create_asset_replacement_plan and create_infrastructure_lifecycle_event 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 gives when-to-use (model interventions BEFORE replacement: roof recoats, boiler retubes, overhauls), an exclusion ("Replacement is NOT an event"), and prerequisites/alternatives (resolve ids via list_asset_types / list_asset_type_groups; list existing events first to reuse a scope). This is textbook 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. It usefully discloses the required authorization scope ('asset_parts:write'), which is real behavioral value. But it omits what happens on a duplicate association (upsert vs. error), whether quantity defaults, and whether the operation is reversible, leaving meaningful gaps for a mutation.

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

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

Two short sentences with zero filler; the operation is front-loaded and the auth requirement is appended. Every clause earns its place.

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

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

For a simple two-required-parameter link tool with no annotations and no output schema, the description covers the core operation and the scope requirement. It still leaves unclear duplicate-handling and return behavior, so it is adequate but not fully complete.

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

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

Schema description coverage is 100%, so all three parameters (part_id, asset_id, quantity) are already documented in the schema. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Link a part to an asset', with a parenthetical clarifying that it creates an association. This clearly separates it from sibling create_part (creates a part) and create_asset (creates an asset). However, it does not explicitly name a sibling alternative, so it stops short of a 5.

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

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

The description says what the tool does but gives no when-to-use guidance and never mentions the alternatives for this domain (e.g., update_asset_part when changing the quantity of an existing link, or delete_asset_part to remove it). An agent must infer the boundaries on its own.

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 well: it discloses upsert semantics, the one-placement-per-asset-global constraint, and a required scope (asset_placements:write). It omits error/conflict behavior and what the response returns, which keeps it short of a 5.

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

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

Three tight sentences, front-loaded with the core action, then the surprising upsert constraint, then the routing to bulk_create and the scope requirement. No sentence is wasted.

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

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

For a mutation tool with no annotations and no output schema, the description covers the critical non-obvious facts: upsert behavior, global single-placement constraint, and auth scope. It does not describe return value or failure modes, leaving a small gap.

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

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

Schema coverage is 100%, so all six parameters are already documented, including x/y normalization and enum for source. The description restates the coordinate frame ('normalized 0-1, origin top-left'), which is largely duplicative of the schema's own x/y descriptions, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('Place an asset on a floorplan') plus the coordinate frame, and materially differentiates itself from update_asset_placement by declaring the operation UPSERTS by asset_id. An agent can tell exactly what this does versus its siblings without opening any schema.

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

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

Explicitly routes bulk work to an alternative ('Use bulk_create with resource="asset-placements" to place many assets at once') and clarifies that re-calling is not a duplicate but a move. Both the when-to-use and when-to-use-something-else conditions 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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose the required authorization scope ('asset_replacement_plans:write'), which is genuine added value. However, it says nothing about mutation side effects, duplicate handling, or whether creating a plan triggers downstream lifecycle/cost changes, leaving significant gaps for a write operation.

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

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

Two sentences, front-loaded with the action and followed by the permission requirement. Nothing is redundant or padded.

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

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

With no output schema and no annotations, the description must stand in for the behavioral profile. It covers purpose and auth scope adequately, which is enough to call the tool, but omits return values, error behavior, and any constraints linking this plan to an existing asset record.

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 7 parameters (including required asset_id and planned_replacement_year, plus enums for status and priority) are already documented in the schema. The description adds no semantics beyond that; the baseline of 3 applies when the schema does the heavy lifting.

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

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

The description names a specific verb and resource: 'Create a new asset replacement plan.' That is unambiguous and distinct from sibling read/write tools. It stops short of explicitly differentiating from update_asset_replacement_plan or bulk_create, but the noun phrase is specific enough to identify the operation.

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

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

No guidance on when to use this versus update_asset_replacement_plan, bulk_create, or list_asset_replacement_plans. There is no mention of prerequisites (e.g., the asset must already exist) or when-not-to-use conditions. The agent must infer usage from the name alone.

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. It usefully discloses the required authorization scope (asset_statuses:write), which is real behavioral context. However, it says nothing about name uniqueness constraints, what the created record contains, or failure behavior — notable gaps 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?

Two short sentences, no filler, with the operation stated first and the prerequisite second. Nothing is wasted.

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

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

For a simple three-parameter create with a fully documented schema and no output schema, the description covers purpose and the auth prerequisite, which is enough to call the tool. It could add uniqueness/validation expectations, but nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents name, module (with enum values and default) and description fully. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Create a new asset status') and adds a clarifying gloss ('lifecycle state for assets') that distinguishes it from the many other create_asset_* siblings. It does not explicitly name or contrast with update_asset_status or list_asset_statuses, so it misses the top tier.

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

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

The description implies the tool is for creating asset statuses but gives no when-to-use guidance, no exclusion against the sibling update_asset_status, and no mention of when a status already exists. The scope prerequisite ('requires asset_statuses:write') is the only actionable usage signal.

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 must carry the behavioral burden, and it does disclose the required write scope, which is genuinely useful auth context. However, it omits whether the name must be unique, whether the new type is immediately available for use, and any idempotency or error behavior.

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

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

Two very short sentences with the action front-loaded and the permission requirement second. No filler or redundancy.

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

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

For a mutation tool with no annotations and no output schema, the scope disclosure is a useful start, but an agent still lacks information about uniqueness constraints and what the response contains. Adequate but with clear gaps.

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

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

Schema description coverage is 100%, so name, group_id, and description are already documented in the schema, including required status and length limits. The description adds nothing about parameter meaning, 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 and resource ('Create a new asset type'), which is clearly distinguishable from update_asset_type and delete_asset_type. It does not differentiate itself from the adjacent create_asset_type_group or bulk_create siblings, but the core purpose is 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?

No guidance on when to use this versus create_asset_type_group, create_asset, or bulk_create, and no prerequisites beyond the scope note. Usage context is left entirely to inference from the name.

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. It usefully discloses the required authorization scope ('asset_type_groups:write'), but says nothing about uniqueness constraints on name, duplicate-name behavior, reversibility, or the response. Useful but incomplete 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?

Three short sentences, action verb first, definition second, prerequisite last. No filler and nothing that could be cut without losing information.

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

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

For a simple 3-parameter create tool with full schema coverage and no output schema, the description covers purpose, domain meaning, and the auth scope. Only edge-case behavior (name collisions, validation failures) is missing, which is a minor gap.

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

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

Schema description coverage is 100% and each of the three parameters (name, color, description) is documented in the schema with constraints like maxLength and a hex-code example. The description adds no parameter detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb+resource ('Create a new asset type group') and adds a definition of what a group is ('organize asset types into logical categories'), which implicitly separates it from the sibling create_asset_type. It stops short of naming the adjacent tools, so differentiation is conceptual rather than explicit.

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 gives implied usage (create a grouping construct for asset types) and states the required scope, but offers no when/when-not guidance or alternatives among the many create_* siblings. Adequate context, no routing help.

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 usefully discloses the auth requirement ('Requires attachments:write scope') and the exactly-one-parent invariant, which are non-obvious operational facts. It says nothing about return values, whether the referenced parent must already exist, or failure behavior, leaving gaps 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?

Three short sentences, zero filler, with the core action front-loaded and the constraint and prerequisite following in logical order. 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 10-parameter mutation tool with full schema coverage, no output schema, and no annotations, the description covers the essentials: what it creates, the parent-selection rule, and the required scope. It could be slightly more complete on return behavior or parent-existence preconditions, but nothing critical 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 description coverage is 100%, so every parameter, including the four mutually exclusive parent IDs, is already documented in the schema. The description restates the parent constraint but adds no format, syntax, or defaulting detail beyond what the schema provides, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Create an attachment record') and enumerates the four valid parent types, which meaningfully scopes the tool. It does not, however, differentiate itself from plausible siblings such as create_asset_document, create_project_document, or upload_file/create_upload_url, which an agent might reasonably consider for similar tasks.

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

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

Usage is implied through the structural constraint ('Exactly one parent ID must be provided') and the required scope, but there is no explicit when-to-use versus alternatives guidance. The agent gets no routing help for choosing between this tool and other document/attachment creation 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 burden and does it well: it discloses the required budgets:write scope, the uniqueness constraint, the 409 refusal on duplicate slots, and that site_id/building_id are not read. These are exactly the behavioral traits an agent needs to avoid a failed call.

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

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

Front-loaded with the core purpose, scope, and constraints in compact prose; every sentence adds a constraint or routing detail. The trailing 'Required:' line is slightly redundant with the schema but still informative given the discrepancy noted.

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

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

For a 7-param mutation tool with no annotations and no output schema, the description covers auth, uniqueness, conflict behavior, and workspace semantics. It is nearly complete; only the required-field discrepancy and lack of an explicit update alternative keep it from a 5.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds useful semantics (module = workspace, O&M/Capital meaning, don't use site_id/building_id), but it also introduces an inconsistency by listing budgeted_amount as 'Required' while the schema's required array contains only year and funding_source.

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

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

Specific verb ('Set') + resource ('annual funding budget') with a concrete anchor to the dashboard Budget tab. It distinguishes itself from update_budget/list_budgets by framing this as the creating/setting action and naming the uniqueness slot it writes to.

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?

Clearly tells the agent when this applies (one row per year and funding source, do not split a year across sites/buildings) and gives the failure condition (a second row for the same slot is refused with 409). It does not explicitly route to update_budget for existing records, so it stops short of full alternative 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 behavioral burden. It usefully discloses the auth scope and the coordinate-pairing rejection rule, but that pairing rule is already documented in the schema, and it says nothing about idempotency, duplicate handling, what is returned, or whether site_id must reference an existing site.

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

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

Two short sentences, front-loaded with the core action and the auth requirement, then the coordinate constraint. No filler or redundancy.

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

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

For a 9-parameter creation tool with no annotations and no output schema, the description covers purpose, permission, and one validation rule. It leaves gaps around the site_id relationship, response/return behavior, and side effects, so it is adequate but not complete.

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

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

Schema description coverage is 100%, so all 9 parameters are already documented in the schema. The description only restates the lat/long pairing constraint already present in those field descriptions, adding no new syntax, format, or dependency detail beyond the 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 ('Create a new building'), so the agent immediately knows this is a building-creation operation. It does not differentiate from adjacent siblings such as create_project_building or create_site, which an agent must disambiguate on its own.

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 a prerequisite (buildings:write scope) but gives no explicit when-to-use guidance, no exclusions, and no pointer to alternatives like create_project_building or bulk_create. Usage is implied from the name rather than stated.

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

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

With no annotations, the description carries the full behavioral burden. It does add genuine value by stating the required write scope (building_types:write), which is not in the schema. However, it omits other behavioral traits such as idempotency, behavior on duplicate names, or any side effects of the creation.

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

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

Two short sentences with the core action front-loaded and the scope requirement second. No redundant or filler content; 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 simple two-parameter create tool, the definition covers the action and the auth requirement, which is adequate. But with no annotations and no output schema, it leaves the return value and any uniqueness/validation behavior unexplained, so it is minimally viable rather than complete.

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

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

Schema description coverage is 100%, so both parameters (name, description) are already documented in the schema. The description adds no syntax, format, or constraint details beyond the schema, so the baseline of 3 applies.

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

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

The description gives a specific verb+resource ("Create a new building type"), clearly distinguishing it from the many sibling create_* tools and from delete_building_type/update_building_type/list_building_types. It does not explicitly name which sibling handles adjacent concerns, but the verb+resource is 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?

There is no when-to-use guidance, no statement of prerequisites beyond the scope, and no reference to alternatives. An agent must already understand the domain to know when this tool applies versus create_asset_type or create_location_type.

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 behavioral burden. It does disclose the required auth scope ('change_orders:write'), which is genuine added context, but says nothing about defaults applied on creation, whether status defaults to draft, validation behavior, or what is returned.

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

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

Two short sentences, front-loaded with the action and the permission requirement, with zero filler. Nothing 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?

For a 9-parameter mutation tool with no annotations and no output schema, the description is too thin. It omits creation defaults, the meaning of the draft/submitted status values at creation time, and any side effects, leaving the agent to rely solely on the schema.

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

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

Schema description coverage is 100%, so all nine parameters including the status enum and the negative-amount credit convention are already documented. The description adds nothing 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?

The description states a specific verb and resource ('Create a new change order'), which is unambiguous. However, it does nothing to distinguish this tool from adjacent siblings like create_work_order, create_purchase_order, or update_change_order beyond the resource name itself.

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

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

There is no when-to-use guidance, no prerequisites beyond the scope note, and no mention of alternatives or related tools. The agent has to infer context entirely from the tool name.

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 must carry the full behavioral burden. It usefully discloses the required auth scope (compliance:write), but omits what happens on success/failure, whether names must be unique, or any side effects – significant gaps 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?

Two short sentences, well front-loaded with the core action first and the permission requirement second. No wasted words; it is appropriately sized if a little sparse.

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

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

For a 6-parameter create tool with no output schema and no annotations, the description covers purpose and auth but omits return behavior and failure/constraint semantics. Adequate but with clear gaps against the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters (including the enum for status and constraints). The description adds no parameter-level meaning beyond that, 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 ('Create a new compliance item') and even disambiguates the domain concept with '(regulatory requirement)'. It does not differentiate from closely-named siblings like create_compliance_record or create_compliance_pm_schedule, so it stops short of a 5.

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

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

The description provides a prerequisite ('Requires compliance:write scope') but no guidance on when to use this versus create_compliance_record or create_compliance_pm_schedule, nor any exclusions. Usage is only implied by the name and scope note.

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

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

With no annotations, the description carries the full burden and does well: it discloses the authorization scope, the required fields, and the semantic effect of the link on compliance status. It omits idempotency/duplicate-link behavior and whether the link is reversible, which are relevant for a write operation.

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

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

Three tight sentences: effect first, then permission requirement, then required fields, then prerequisite lookup steps. Every sentence earns its place with no redundancy.

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

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

No output schema and no annotations, so the description must stand alone; it covers auth, required inputs, and the pre-call lookup workflow. It leaves out what the tool returns and any guidance on the optional weight parameter or on modifying an existing link.

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 four parameters including weight are already documented in the schema, and the description adds no parameter-level meaning beyond restating the three required fields. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (link) and both resources (PM schedule, compliance item), and explains the functional consequence: completing the schedule keeps the item compliant. This distinguishes it cleanly from siblings like create_compliance_item, create_pm_schedule, and update_compliance_pm_schedule.

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

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

Gives concrete preconditions: requires compliance:write scope and instructs the agent to resolve both ids via list_compliance_items and list_pm_schedules first. It doesn't state when not to use it (e.g., use update_compliance_pm_schedule to change an existing link), so it falls short of full when/when-not coverage.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the required auth scope, which goes beyond the schema, but says nothing about mutation behavior such as idempotency, duplicate handling, or what the created record affects.

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

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

Two short sentences, front-loaded with purpose followed by the auth prerequisite. No wasted words.

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 create tool with 7 fully-documented params, no output schema, and no annotations, the definition is adequate but thin. It omits any guidance on the linked entities (compliance item, PM schedule, work order) that would help an agent invoke it correctly.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema. The description adds no parameter-level detail beyond that, so the baseline of 3 applies.

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

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

States a specific verb (Create) and resource (compliance record) and clarifies semantics by equating it with an 'audit trail entry.' However, it does not differentiate from close siblings like create_compliance_item, create_compliance_pm_schedule, or update_compliance_record.

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 a concrete prerequisite ('Requires compliance_records:write scope'), which is useful context. But it offers no when-to-use vs when-not guidance and does not distinguish this from the sibling create/update compliance 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 provided, the description carries the full burden. It usefully discloses the required auth scope (contracts:write), but says nothing about idempotency, validation behavior, or what the call returns. "Create" implies mutation but no further behavioral traits are surfaced.

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

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

Two short sentences, front-loaded with the action and followed by the key constraint. No wasted words and nothing that could be trimmed.

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

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

For a 10-parameter mutation tool with no output schema and no annotations, the description is thin. The schema fully documents inputs and the scope requirement is noted, but the agent receives no information about the response shape or side effects, leaving gaps for a fairly complex create operation.

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

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

Schema description coverage is 100%, so every parameter is already documented (title, category, dates, company_id as vendor, annual_cost, quality_score, etc.). The description adds no additional meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ("Create a new contract"), which is clear and unambiguous. It does not distinguish itself from related sibling tools like create_contract_document or create_contract_site, but the core purpose is evident.

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 offers no when-to-use guidance, no prerequisites beyond the scope requirement, and no mention of alternatives such as bulk_create. An agent gets no routing help for choosing this over related creation 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?

No annotations are provided, so the description carries the full burden. It does add the meaningful authorization requirement (contract_documents:write scope), which is genuine behavioral context a mutation tool should disclose. However, it omits whether duplicate records are rejected, what the response contains, or how the file_path prerequisite is satisfied.

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

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

Two short sentences with no filler, and the core action is front-loaded before the scope requirement. 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 6-parameter mutation with no annotations and no output schema, the description is minimal. It covers the action and auth scope, but the description is adequate at best given the surrounding tool family requires the agent to infer the upload-then-create workflow.

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

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

Schema description coverage is 100%, so all six parameters (contract_id, file_name, file_path, file_size, file_type, uploaded_by) are already documented in the schema. The description adds no additional parameter meaning beyond that, making the baseline 3 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?

States a specific verb (Create) and resource (contract document record), so an agent can tell it creates a contract document rather than a contract. It does not differentiate itself from near siblings like create_contract, create_attachment, or create_project_document, so it lands at 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 only states the required scope. It gives no guidance on when to use this versus upload_file, create_upload_url, or create_attachment, nor that a file must be uploaded first to obtain file_path. No when/when-not or alternatives are provided.

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 usefully discloses the required write scope, which most schemas do not express. However, it says nothing about idempotency, duplicate-assignment behavior, or what happens to an existing link, which matter for an association-creating mutation.

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

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

Two sentences, zero filler, with the operation stated first and the authorization prerequisite second. Nothing is padded or restated from 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 simple two-parameter association tool with no output schema, the description covers the operation and the auth requirement, which is most of what an agent needs. It stops short of explaining failure modes (e.g., duplicate link, nonexistent contract/site), which no structured field covers either.

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

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

Schema coverage is 100% and both parameters are required with descriptions, so the schema already documents them fully. The description only adds the mapping semantics (contract_id → contract, site_id → site) already implied by the tool name, 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 (Assign) and the two resources involved (contract, site), so the agent knows this creates a contract-to-site association rather than a new contract or site. It does not explicitly contrast with siblings like create_contract or list_contract_sites, but the implied operation is 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 implies when to use it (when a contract needs to be tied to a site) and gives a prerequisite (contract_sites:write scope), but offers no when-not guidance and never mentions delete_contract_site or list_contract_sites as alternatives for managing the same association.

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

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

With no annotations, the description carries the full burden, and it does disclose a genuine behavioral fact: the required cost_categories:write scope, which is real auth context. Beyond that it says nothing about side effects, whether the category must be unique, or what is returned, so it only partially covers the behavioral gap left by missing annotations.

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

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

Two short sentences with zero filler; the purpose is front-loaded and the scope constraint follows immediately. Every word 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 simple three-parameter create tool with full schema coverage and no output schema, the description is minimally adequate. It omits any note about hierarchy semantics (parent_id nesting) or what a successful creation yields, which would have made it complete given the absence of annotations.

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

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

Schema description coverage is 100%, so the schema already documents name, is_active, and parent_id with meaningful descriptions. The description adds no parameter-level detail beyond that, so the baseline of 3 applies.

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

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

States a specific verb+resource ('Create a new cost category'), so the agent knows exactly what it does. However, it offers no differentiation from similarly-shaped siblings such as create_work_category or create_part_category, leaving the agent to infer the distinction from the name alone.

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

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

There is no when-to-use guidance, no prerequisite context, and no mention of alternatives (e.g. update_cost_category or list_cost_categories). The only routing signal is the scope requirement, which is not the same as 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 full burden and does so: it discloses that rows are overrides only, gives the built-in defaults for un-overridden tiers, states the duplicate-409 behavior, and names the required 'los_targets:write' scope. These are real behavioral traits beyond what the schema exposes.

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

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

Purpose is front-loaded in the first clause, and each subsequent sentence contributes distinct information (defaults, modifier semantics, duplicate handling, scope) with no redundancy or filler.

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

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

For a two-parameter mutation with no output schema and no annotations, the description covers purpose, defaults, value semantics, collision handling, and auth scope. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the schema already documents that modifier <1 tightens and >1 relaxes. The description goes further by supplying the per-tier default values (critical 0.6, high 0.8, medium 1.0, low 1.4) and explaining the domain effect on targets held by facilities in that tier, adding meaning the schema lacks.

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 ('Override the criticality modifier') scoped to 'one tier', which is precise enough to distinguish it from update_criticality_modifier and the other create_* siblings. An agent immediately knows this creates a per-tier override row rather than a general setting.

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

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

Explicitly routes the agent away from this tool when an override already exists: 'a duplicate returns 409, so call list_criticality_modifiers and update the existing row instead.' That names both the alternative tool and the condition that selects it, which is exactly the when/when-not guidance the dimension asks for.

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

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

No annotations are provided, so the description carries the full burden. It discloses the required OAuth scope 'custom_fields:write,' which is a useful behavioral trait beyond the schema. However, for a mutation tool it omits other important traits: whether creation is idempotent, what happens if a definition with the same field_name already exists, and what side effects occur. The single auth disclosure earns a 3 but leaves significant gaps.

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

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

The description is two short sentences with zero wasted words, and the core purpose is front-loaded. It is appropriately sized for what it attempts to say, though it is under-specified rather than maximally informative, so a 4 rather than a 5.

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

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

For a create tool with seven parameters, no output schema, and no annotations, the description is too sparse. It does not explain valid values for entity_type (the schema provides only a plain string with maxLength, no enum), does not mention that field_options applies only to select-type fields, and does not describe post-creation behavior. Schema coverage helps, but the description fails to fill important contextual gaps.

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

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

Schema description coverage is 100%, so all seven parameters are already documented in the schema, including the enum for field_type. The description adds no additional parameter meaning. Per the rubric, when schema coverage is high the baseline is 3, and this description does not exceed that 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?

The description states a specific verb and resource: 'Create a new custom field definition.' This clearly conveys what the tool does, but it does not differentiate from its closest sibling create_custom_field_value (which creates values, not definitions), nor does it mention the related list/get/update/delete tools for the same resource. A 4 is appropriate: clear purpose, no sibling 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?

The only usage guidance is 'Requires custom_fields:write scope,' which is a prerequisite but not when-to-use guidance. There is no mention of alternatives (e.g., create_custom_field_value for setting values on existing fields), no conditions for use, and no exclusions. The agent must infer everything from the name.

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 that writes upsert on (entity_id, field_definition_id) making batch replay idempotent, and states the required custom_fields:write scope. It does not say whether unmentioned typed columns are cleared on an upsert, which is the main remaining behavioral gap.

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

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

Front-loaded with the verb and resource, then typed-column guidance, then idempotency and auth requirements. Every sentence adds information and none is wasted.

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

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

Complete for a seven-parameter create/upsert tool with no output schema or annotations: params, idempotency, auth scope, and column-selection logic are all covered. Only the overwrite/clear behavior on upsert is left unspecified.

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 by mapping field_type values to the correct typed column (text/select, number, date ISO, boolean) and explaining the dispatch behavior of the legacy `value` shim. This goes beyond restating the schema.

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

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

States a specific verb (create/upsert) and resource (custom field value for an entity), and the upsert framing immediately distinguishes it from siblings like create_custom_field_definition and update_custom_field_value. An agent can identify the operation 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 tells the agent to prefer the typed value_* column matching the field definition's field_type, and offers the `value` shim as an alternative with its dispatch rule. It stops short of stating when to use this tool versus update_custom_field_value, but the upsert semantics make that distinction largely internal.

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 of behavioral disclosure. It mentions the necessary scope (a behavioral trait), but omits critical details such as return behavior, side effects, validation rules, and whether the operation is idempotent. For a mutation tool, this is minimal 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?

Two short sentences with no wasted words. The primary purpose is front-loaded, followed by the scope requirement. Every sentence earns its place, making it highly efficient.

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 8 parameters, no annotations, and no output schema, the description is notably incomplete. It fails to describe return values (which are not covered by an output schema), error handling, or any behavioral nuances. An agent would need to infer much from the schema alone.

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%, meaning all 8 parameters (including required ones) are documented in the schema. The description adds no additional parameter semantics beyond what the schema provides. Baseline 3 is appropriate when the schema fully documents parameters.

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

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

States a specific verb (Create) and resource (expense), clearly conveying the tool's function. It does not explicitly differentiate from sibling creation tools, but the resource is unique enough for an agent to identify it. No misleading or vague language.

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?

Only provides a required scope (expenses:write) as a prerequisite. No guidance on when to use this tool versus alternatives like bulk_create or update_expense, nor any context about appropriate scenarios. The scope requirement is useful but insufficient for usage decision-making.

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 load; it discloses the required write scope ('floorplans:write') and the pipeline context (invoked per page of an uploaded PDF). It does not explain what happens after creation (the pending/detecting status lifecycle) or the failure mode when both or neither id is supplied, leaving some behavioral gaps for an unannotated 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?

Four short sentences, front-loaded with the action, then the key constraint, then the relevance caveat, then the auth requirement. Every sentence carries information an agent needs; nothing is restated from the schema.

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

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

For a 10-parameter, unannotated tool with no output schema, the description covers the highest-risk decisions: which id to pass, whether to call it at all, and what scope is needed. It leaves the detection-status lifecycle and post-create behavior unexplained, but the required fields are self-documenting in the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. However, the description adds a rule the schema does not state anywhere: EXACTLY ONE of building_id or site_id, and it clarifies the semantic difference between them (per-building floor vs site-level/campus plan). That is genuine added meaning beyond the field 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?

States a specific verb+resource ('Create a floorplan row') and immediately narrows scope by explaining the two mutually exclusive ownership modes (per-building vs site-level/campus). It also flags the typical caller (the web app), which lets an agent judge relevance without opening the schema.

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

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

Explicit when-not guidance: 'MCP clients rarely need to call this directly since they do not upload the PDF itself.' Combined with the exactly-one-of constraint, an agent knows both whether to use it and how to shape the call.

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 present, so the description carries the full behavioral burden. It usefully discloses the coordinate convention (normalized 0-1, origin top-left) and the required write scope, but says nothing about idempotency, defaults for source/reviewed, or error behavior on an existing or invalid region.

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

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

Three short sentences, front-loaded with purpose and with no filler. The coordinate sentence partly overlaps the schema's polygon description, which is the only minor redundancy.

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

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

For a mutation tool with no annotations and no output schema, the description covers scope and coordinate conventions but omits what the call returns (e.g., the new region ID) and the behavior of schema defaults. Adequate but not fully complete.

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

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

Schema coverage is 100%, so all seven parameters are already documented, including polygon coordinates and the location_id resolution note. The description restates the coordinate system and the optional linkage rather than adding 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 and resource ('Create a region ... on a floorplan') and the parenthetical 'labeled room or zone' clarifies what a region is, distinguishing it from create_location and create_floorplan. It lacks an explicit sibling reference, but the scope is 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?

Provides some context: the optional Location linkage via location_id and the required floorplan_regions:write scope. However, it offers no when-to-use vs when-not guidance relative to siblings like update_floorplan_region or create_location, leaving usage to inference.

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

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

With no annotations, the description carries the full burden and does well: it discloses the snapshot-at-attach behavior, that answering/completing happens in-app rather than via this API (a key expectation-setter for a create tool), and the required write scope. It does not cover idempotency or re-attach behavior, so it falls short of 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?

Five sentences, each doing distinct work: purpose, snapshot semantics, the alternative path, the in-app boundary, and the scope requirement. The core action is front-loaded and nothing is redundant.

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

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

For a 3-param create tool with no output schema and no annotations, the description covers action, downstream lifecycle (answering outside the API), the sibling alternative, and auth scope. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents template_id (published-only, draft/archived rejected), subject_id resolution, and the subject_type enum. The description adds no syntax or format detail beyond that, so the baseline of 3 applies.

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

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

States a specific verb (attach) and resource (a published form to one record) and immediately names the concrete use case (inspection/checklist on an existing work order). It distinguishes itself from the PM-schedule path rather than blurring into the sea of create_* siblings.

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

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

Explicitly tells the agent when to call this (per-record attach) versus when to use an alternative (set form_template_id on the schedule for every generated work order), and adds the form_responses:write scope prerequisite. Both 'when' and 'when-not' are covered.

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

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

With no annotations, the description carries the full burden and does well: it discloses the auth requirement (form_templates:write scope), the draft-by-default lifecycle state, and the validation behavior on publish ('rejected if any question is malformed'). It stops short of describing failure modes or the returned identity, but the behavioral coverage is strong for an unannotated 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?

A single dense paragraph with the core definition front-loaded, followed by the workflow, alternatives, and auth scope. Every clause carries information, though the run-on structure with multiple parentheticals is slightly heavy for a description this size.

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 create tool with no output schema and no annotations, this covers the essential workflow, dependencies, validation constraint, and permission requirement an agent needs to call it correctly. The only gap is the absence of any statement about what the call returns (e.g., the created template ID) needed for the subsequent item-creation step.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including the enum meanings for module and status. The description adds only a slight gloss on the status parameter via the publish step, without format or default detail beyond the schema. 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?

States a specific verb+resource ('Create a form template') and immediately clarifies what a form template is ('a reusable inspection, checklist, compliance, or survey definition'). It distinguishes itself from siblings by naming create_form_template_item, bulk_create, and update_form_template, 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?

Explicitly frames the tool as 'Step 1 of building a form' and lays out the full workflow: create as draft, add questions via create_form_template_item or bulk_create, then publish via update_form_template status=published. It also names the exclusion condition (publishing is rejected if any question is malformed), giving genuine 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?

No annotations are supplied, so the description must carry the behavioral burden. It does disclose two real traits beyond the schema: the required form_template_items:write scope and the ordering requirement ('in order'). It does not say what happens on validation failure, whether sort_order collisions are rejected, or whether the created item id is returned.

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

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

Two sentences, front-loaded with the core action and scoped by the required permission. No filler or repetition of the tool 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 10-parameter, nested-object create tool the description plus the very detailed schema cover the invocation well, including the bulk alternative and permission requirement. The only shortfall is that with no output schema and no annotations, the description never indicates what a successful call returns (e.g. the new item id) or how to sequence references to 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 the schema itself is unusually rich (per-type config shapes, options rules, visible_when operator matrix, item_key guidance). The description adds no parameter meaning beyond that, 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 precise verb and resource and clarifies the resource is 'one question (item)' added to a form template, which cleanly separates it from create_form_template (makes the template) and update_form_template_item (edits an existing item). It also names the bulk_create sibling it is an alternative to.

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 how to use it ('calling this once per question in order') and names the alternative path ('use bulk_create on form-template-items'), which is exactly the when/when-else routing an agent needs.

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

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

With no annotations, the description carries the full burden, and it does add real value: it discloses server-side computed fields (length_m, slope_pct, risk_score) the caller must not supply, the required infrastructure_assets:write scope, and the CRS/axis order. It is silent on duplicate feature_code handling, idempotency, error behavior, and what the call 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?

Four tight clauses, front-loaded with the action, then the geometry contract, then the computed-field caveat, then the auth prerequisite. No filler and no repetition of schema text.

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 56-parameter mutation with no annotations and no output schema, the description covers the highest-risk items (geometry format, computed fields, scope) but omits asset-type-specific applicability of fields (e.g. from_street/to_invert_m are segment-only) and any statement of what a successful call returns.

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 95%, so the baseline is 3; the description earns one more by adding CRS (EPSG:4326) and coordinate order ([longitude, latitude]) that the schema's geometry description omits, plus the segment/node-to-geometry-type mapping. The remaining 50+ attributes are covered by the schema itself.

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

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

States a specific verb and resource ('Create an infrastructure asset') and immediately disambiguates the two sub-types ('feature - segment or node'). It does not, however, contrast itself with the nearby create_asset sibling, so an agent must infer which entity family applies.

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 gives format constraints but no when-to-use guidance: nothing says when to use this versus create_asset, bulk_create, or create_infrastructure_network. There are no exclusions or preconditions beyond the scope 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 to lean on, the description usefully discloses two behavioral facts: author is auto-attributed from the API key, and the call requires infrastructure_asset_comments:write scope. It stops short of describing the response, validation limits (10000-char cap is only in the schema), or what happens on failure.

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

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

Three tight sentences, front-loaded with the action, followed by the author-attribution caveat and the scope requirement. No filler or redundancy.

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

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

For a simple two-parameter creation tool with no output schema and no annotations, the description conveys the essential auth and attribution context an agent needs. It could be stronger by clarifying the return or how it relates to the other comment-creation tools.

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 required parameters (feature_id, comment) are already fully documented in the schema, giving a baseline of 3. The description adds only the negative guidance that user_id should not be supplied, which is marginal added meaning.

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 (add) and resource (comment on an infrastructure feature), which is unambiguous. However, it does not differentiate from the many sibling comment-creation tools (create_asset_comment, create_project_comment, create_work_order_comment), which an agent must disambiguate by name alone.

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

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

Usage is implied by the purpose statement, and there is one concrete operational cue ('do not pass user_id'). But there is no explicit when-to-use/when-not guidance or reference to the corresponding list/get/update/delete comment siblings, so the agent must 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?

With no annotations, the description carries the full burden, and it does usefully disclose two traits: the write-scope requirement and the server-side derivation of work_order_number. It stops short of covering mutation semantics such as idempotency, permission prerequisites beyond scope, or side effects on purchase-order balances.

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

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

Three short sentences, each front-loaded and each earning its place: purpose, a field-level warning, and an auth requirement. No filler.

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

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

For a mutation create tool with eight parameters and no annotations or output schema, the description covers scope and the derived field but omits routing guidance against sibling create_asset_cost and broader side-effect behavior. Adequate but with clear gaps.

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

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

Schema coverage is 100%, so baseline is 3, and the description adds genuine value by warning that work_order_number is server-derived and must not be set – a caveat absent from the schema. It does not elaborate on the interplay between work_order_id and purchase_order_id, which the schema itself handles.

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

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

The description gives a specific verb+resource ('Record a cost against an infrastructure feature'), which is clear on its own. It does not, however, distinguish itself from the closely-named sibling create_asset_cost, leaving the agent to infer that this tool is the infrastructure-feature-specific variant.

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

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

There is no when-to-use vs when-not guidance and no mention of the alternative create_asset_cost sibling, which is the most likely point of confusion given the near-identical naming. The only directive is about which field not to set, not about tool selection.

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

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

With no annotations, the description carries the full burden. It usefully discloses the required scope (infrastructure_asset_documents:write) and clarifies that only metadata is attached, not file bytes. It says nothing about idempotency, duplicate file_path handling, or what the call returns.

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

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

Three short sentences, zero padding, and the core action is front-loaded before the workflow prerequisite and the permission note.

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 and no output schema, the description covers the critical prerequisite chain and the auth scope. It would be stronger with a note on failure modes (e.g. invalid file_path) or confirmation of what is returned, but nothing essential to calling it correctly is missing.

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

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

Schema description coverage is 100%, so all seven parameters are already documented in the schema. The description only adds provenance for file_path (it comes from create_upload_url), which is marginal added value beyond the schema text.

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 ('Attach document metadata to an infrastructure feature'), which cleanly separates it from create_asset_document and create_project_document by naming the parent entity type. It doesn't explicitly name those siblings, but the scoping word 'infrastructure' is enough for an agent to disambiguate.

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

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

Gives a concrete ordering rule: upload bytes first via create_upload_url, then pass the returned file_path here. That is real when-to-use guidance and names the prerequisite tool. It stops short of saying when NOT to use it (e.g. for asset or project documents).

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 usefully discloses the required authorization scope (infrastructure_asset_inspections:write), which is real behavioral context. But it says nothing about mutation semantics, uniqueness constraints, whether the feature must already exist, or what is returned on success.

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

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

Two short, front-loaded sentences with zero filler; the core purpose comes first and the scope requirement follows. Nothing is padded or redundant.

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

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

For an 8-parameter mutation tool with a nested JSON object and no output schema, the description covers purpose and authorization but omits any note on required inputs or how the nested defects structure is used. It is minimally adequate but leaves meaningful gaps an agent would want filled.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, establishing the baseline of 3. The description adds no additional meaning about required fields (feature_id, inspection_date) or the free-form defects JSON object, so it does not exceed the 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?

The description states a specific verb+resource ('Record an inspection against an infrastructure feature'), which is clear and distinct from generic create_asset tools. However, it does not differentiate itself from close siblings like create_asset_condition_assessment or the inspection-related update/list tools, leaving the agent to infer the boundary from the name alone.

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

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

Usage is implied by the verb 'record' and the stated write scope, which is a genuine prerequisite. There is no explicit guidance on when to use this versus update_infrastructure_asset_inspection or create_asset_condition_assessment, nor any note about required prior state (e.g., an existing feature).

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 uniqueness constraint, the exact failure mode (duplicate returns 409), and the required scope (infrastructure_asset_parts:write). It does not describe whether the association can later be updated or what a successful response contains.

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

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

Three short sentences, zero filler, with the action stated first and the constraint and scope following. Front-loaded and every clause earns its place.

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

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

For a small 3-param create tool with no annotations and no output schema, the description covers the action, the uniqueness constraint, the error code, and the required scope — enough for an agent to invoke it correctly. Only the return behavior and quantity semantics are unaddressed, which is minor.

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 feature_id and part_id are already fully documented in the schema; the description reinforces their pairing but adds no syntax. quantity (default 1) is not addressed in the description, though the schema covers it.

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

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

States a specific verb and resource ('Associate a part with an infrastructure feature'), which is clearly distinguishable from the sibling create_asset_part by the infrastructure-feature target. It stops short of naming the sibling it differs from, so an agent must infer the routing.

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

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

The description explains the constraint (unique feature_id/part_id pair) but gives no guidance on when to use this versus create_asset_part or create_infrastructure_asset, and no prerequisites beyond scope. No when/when-not framing is present.

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

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

With no annotations, the description carries the full burden and does disclose two non-obvious behaviors: is_builtin is always forced to false regardless of input, and a specific write scope is required. It still omits side effects like whether the code must be unique tenant-wide or what is returned, so it is good 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?

Three short sentences, zero filler: what it creates, the prohibition, the auth requirement, in that order. Nothing could be removed without losing information.

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

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

For a mutation tool with no annotations and no output schema, the description covers the key traps (builtin prohibition, forced flag, required scope). What is missing is any note on return payload or uniqueness constraints on code, but the essentials for correct invocation are present.

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

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

Schema description coverage is 100% with per-field descriptions and a category enum, so the schema already documents all six parameters. The description adds no format, default, or inter-parameter semantics beyond what the schema states, which is the baseline case.

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 (create an infrastructure feature class) and qualifies it as tenant-defined, which implicitly contrasts with the builtin classes it cannot touch. It does not explicitly name a sibling tool, but the name-space is unambiguous enough that an agent won't confuse it with update_/delete_/list_ variants.

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

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

Gives a clear when-not condition ('Builtin classes are managed by AssetLab and cannot be created via API') and a prerequisite (infrastructure_feature_classes:write scope). No explicit routing to alternative tools, but the exclusion plus scope requirement is more than most siblings offer.

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 still discloses meaningful traits: the write-scope auth requirement and the resolution behavior (each feature picks the most specific matching scope). It does not describe idempotency, error behavior, or side effects of creation, leaving some behavioral gaps.

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

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

Purpose is front-loaded and the dense single block earns its length for a 20-parameter tool. A few clauses (e.g., the parenthetical on replacement pricing/scheduling) drift toward domain lore rather than call-time guidance, keeping it just under fully 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?

For a 20-param tool with no output schema, it supplies the essential conceptual frame (scope resolution), a key prerequisite (list first), auth requirement, and what not to model. It omits operational return/side-effect detail, but the rich schema covers per-field semantics.

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 schema itself already explains the scope composition ('omit for a material-wide scope; at least one of feature_class/material is required') and how bands ladder. The description's restatement of the scope model (feature_class, material, optional diameter band) largely mirrors the schema, so it stays at the documented 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 + resource ('Create a lifecycle strategy event') and immediately frames the domain model: events attach to a SCOPE, never to individual features. This implicitly distinguishes it from asset-level lifecycle-event siblings by contrasting scope-based vs feature-based attachment.

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 routing guidance: model pre-replacement interventions (crack sealing, relining, resurfacing) and, critically, states that replacement is NOT an event. It also advises listing existing events first to reuse a scope. No explicit sibling tool is named, so it stops short of a full when/when-not/alternative mapping.

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. It discloses duplicate behavior (409), permission and plan requirements, derivation math for criticality-adjusted targets, scale constraints ('Derived targets never leave the metric's scale'), metric semantics including what is unavailable ('Average risk is not available for infrastructure'), and unit clarification ('Not money').

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

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

The description is front-loaded with purpose and tightly organized around duplicate handling, derivation rules, metric semantics, and prerequisites. It is somewhat long and includes an illustrative computation example and minor redundancy ('All three metrics run 0-100' partly repeats schema bounds), but most content is useful for this 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 no annotations, no output schema, and a 4-parameter mutation tool whose behavior includes derived values and permissions, the description is complete. It covers error handling, prerequisites, metric semantics, derivation behavior, scale limits, and sibling routing, leaving no critical gaps 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, but the description adds meaningful semantics beyond the schema: metric direction (higher-is-better vs. lower-is-better), metric scale and types, and the need for feature_class to exist and be resolved first. It does not elaborate on the optional 'active' parameter, leaving that to the schema, so it falls 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 with clear scope: 'Set the technical Level of Service target for one infrastructure feature class and metric.' It distinguishes this creation tool from update by explaining the duplicate 409 case and directing the agent to update the existing row instead. An agent can identify the tool's purpose 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?

The description gives explicit when-to-use context: one base target per feature class and metric, set once for the organization. It names the alternative path for duplicates ('update the existing row instead') and lists prerequisites (los_targets:write scope, Level of Service and Infrastructure plan features) and ordering (resolve feature_class first via list_infrastructure_feature_classes).

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 burden. It usefully discloses the required auth scope ('infrastructure_networks:write scope'), which is genuine value beyond the schema. However, it omits failure/validation behavior (e.g., feature_class must pre-exist) and says nothing about what is returned upon creation.

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

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

Two tight sentences, with the core action front-loaded and the permission requirement trailing. No filler or redundancy; nothing wasted.

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

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

For a create tool with no output schema and full schema coverage of params, the description gives purpose, conceptual definition, and auth requirement, which is largely sufficient. It could optionally mention the required pre-existing feature class or the created object's response, but 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 schema already documents all six parameters in detail, including the criticality enum semantics and the feature_class pattern. The description adds only the general hint that a single feature class is bound, so the 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?

States a specific verb+resource ('Create an infrastructure network') and adds a conceptual definition ('a named grouping of features bound to one feature class') that distinguishes it from create_infrastructure_feature_class and create_infrastructure_zone. It does not explicitly name or contrast with siblings, but the semantic scope is clear.

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

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

The description provides no when-to-use guidance, no alternatives, and no exclusions. It only states a permission prerequisite (write scope), which is a precondition rather than usage direction. An agent must infer the use case from the resource name alone.

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 present, the description carries the full burden and does disclose two behaviors beyond the schema: the (network_id, name) uniqueness constraint and the required infrastructure_zones:write scope. It does not cover error behavior or idempotency, but the auth and uniqueness disclosures are meaningful context for a mutation tool.

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

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

Three tight sentences, front-loaded with the core action, followed by the boundary format and the two constraints. It is efficient, though it partially restates boundary detail that already lives in the schema, a minor redundancy.

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

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

For a 4-required-param mutation tool with no annotations and no output schema, the description covers scope, uniqueness, and the key input shape, which is most of what an agent needs. It stops short of describing failure modes or return payload, leaving a small gap given the absence of an output schema.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, making 3 the baseline. The description adds only the boundary-shape nuance (Polygon vs. MultiPolygon for separate pieces), which is also present in the boundary property's schema description, so it adds little beyond structured data.

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 ('Create an operational hydraulic boundary') and immediately enumerates the concrete kinds (pressure zone, DMA, sewershed), which lets an agent distinguish it from nearby siblings like create_infrastructure_network and create_service_area. The resource is named precisely enough to route 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?

The description implies usage via the hydraulic-boundary framing and the (network_id, name) uniqueness rule, but never states when to choose this tool over a related one (e.g., create_infrastructure_network for the network itself, or create_service_area). There are no explicit exclusions or alternatives, so the agent must 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?

With no annotations, the description carries the full burden. It usefully discloses the required auth scope (invoices:write), which is real behavioral context, but says nothing about side effects, duplicate invoice_number handling, validation of amount, or what a successful creation 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?

Two short sentences, zero waste, with the action front-loaded and the auth constraint appended. Appropriately sized for the content it contains.

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

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

For a 14-parameter create tool with no annotations and no output schema, the description does the minimum. The rich schema covers inputs, but the absence of any statement about return value or post-creation behavior leaves a gap an agent would want filled.

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

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

Schema description coverage is 100% with 14 well-described properties, so the schema already documents each field (amount, dates, IDs, status enum). The description adds no parameter meaning beyond that, which is the baseline 3.

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

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

The description states a specific verb+resource ('Create a new invoice'), which is immediately parseable. It does not differentiate from the many sibling create tools (create_expense, create_purchase_order, create_contract), so it stops short of a 5.

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

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

No guidance on when to use this versus alternatives such as create_expense or bulk_create, and no prerequisites beyond the scope note. The agent gets no routing help in a very crowded create_* namespace.

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 usefully discloses the required permission scope, which is real behavioral context, but says nothing about side effects, whether the location must be unique, what happens on duplicate names, or what the response returns.

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

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

Two short sentences, zero filler, purpose front-loaded ahead of the permission requirement. Nothing is wasted.

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

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

For a 6-parameter mutation tool with no annotations and no output schema, the description covers purpose and auth but omits meaningful gaps: that building_id must reference an existing building, how location_type_id relates to location_types, and whether the call is idempotent. The rich schema fills much of the gap, keeping this at a minimum-viable level.

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

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

Schema description coverage is 100% with per-parameter descriptions (name, building_id, floor, area, type, location_type_id) and constraints, so the schema does the heavy lifting. The description adds no parameter-level meaning beyond what the schema already documents.