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

Adds substantial behavior beyond the annotations: per-item independent processing, one failure not affecting others, per-item results returned, required {resource}:write scope, and the rate-limiting cost of 1 request. These are exactly the operational facts an agent needs before issuing a bulk write.

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 purpose, then failure semantics, return behavior, permissions and rate-limit cost. 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?

For a mutation tool with no output schema, the description covers failure isolation, return granularity, auth scope and rate limiting. It stops short of describing the per-item result shape or how to correlate failures back to input items, which would fully close the loop.

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 (items max 100, resource enum), so the schema carries the burden. The description's 'max 100' and 'same fields as the single-create endpoint' framing adds only marginal meaning on top of that.

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 scoped as bulk creation ('Create multiple records of a resource type in one API call (max 100)'), which cleanly separates it from the many singular create_* siblings and from bulk_update. The scope constraint is stated up front.

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 implies when to reach for it (multiple items in one call, capped at 100) and notes the rate-limit economics ('Counts as 1 request'), but never explicitly says to prefer bulk_create over looping single create_* calls or names an alternative for >100 items.

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

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

Annotations already declare the safety profile (destructive, idempotent, not read-only), yet the description adds genuinely new operational facts: the 100-item cap, that each item is processed independently so one failure does not affect others, that per-item results are returned, and that {resource}:write scope is required. This is exactly the beyond-annotation disclosure that earns a top score.

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 ordered from purpose to limits to failure semantics to permissions to rate limiting. Each sentence carries a distinct operational fact with no filler or repetition.

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

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

With no output schema, the description usefully states that per-item results are returned, and it covers limits, auth scope, and failure isolation. The one residual gap is the shape of the per-item payload — since items use additionalProperties, the description never notes that updatable fields depend on the chosen resource type.

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% for both parameters, so the baseline is 3. The description repeats the item contract ("Each item must include an 'id' field (UUID)") which is already stated verbatim in the items schema, and adds no new syntax or constraint information about the resource enum.

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

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

States a specific verb and resource with scope: "Update multiple records of a resource type in one API call (max 100)." The batch nature and the resource-agnostic "resource type" framing clearly distinguish it from the 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?

Provides clear context for when this tool is worthwhile: it handles up to 100 records and "Counts as 1 request for rate limiting," which implicitly motivates choosing it over repeated single-record updates. It stops short of naming the alternative (update_<resource>) or an explicit when-not condition, so it is clear but not fully routing.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the required 'assets:write' scope and the mandatory hierarchy-ordering constraint. It does not cover failure modes or what happens with invalid IDs, keeping it short of a 5.

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

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

Front-loads purpose and auth scope, then the operational hierarchy rules, with no filler. Given 38 parameters the length is proportionate, and each sentence conveys an actionable constraint.

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-param creation tool with no output schema, the description covers the two cross-cutting concerns an agent most needs: write scope and ID-resolution order. It omits that only 'name' is required and says nothing about the response, but the essential preconditions 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%, and the schema already annotates site_id/building_id/location_id/system_id with their resolve-order hints. The description's hierarchy explanation largely restates that, adding little new per-parameter meaning. Baseline 3 is appropriate when the schema carries the detail.

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

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

States a specific verb and resource ('Create a new asset'), which is clear on its own. However, it does not differentiate from the closely-named sibling create_infrastructure_asset or other create_* tools, so an agent has no textual cue for which create to pick. Clear but lacks 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?

Provides a concrete top-down resolution workflow (list_sites -> list_buildings -> list_locations, and list_system_classes -> list_system_groups -> list_systems) that tells the agent how to gather prerequisites before calling. It gives no explicit when-not or alternative-tool guidance versus sibling create tools, so it is clear context without exclusions.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description goes well beyond them: it discloses the rejection rule ('work that adds neither changes nothing and is rejected'), the side effect that net book value and remaining life re-base from occurred_on, the invariant that purchase_date is NEVER changed, and the required asset_betterments:write scope.

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 work-defining scope, required fields, and the crucial never-change-purchase_date rule are front-loaded, and every subsequent sentence carries distinct information (rejection rule, alternatives, prerequisite, scope). No filler despite the density.

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

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

For a 9-parameter mutation with no output schema, the description covers what the tool does, the field requirements, the behavioral consequences, the sibling routing, and the 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, but the description adds real constraint meaning absent from the schema: it specifies the 'at least one of capitalized_amount or added_life_years' requirement and clarifies occurred_on means the in-service date, not the invoice date. This is meaningful supplementation above the schema.

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

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

The description names a specific verb and resource ('Record capital work') and gives three concrete examples (elevator modernization, boiler retube, component replacement). It explicitly distinguishes this from sibling tools asset_lifecycle_events and condition assessments, so an agent can route correctly without opening the schema.

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

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

It states when to use this ('capital work that ALREADY extended a facility asset's life'), when not to ('work expected in future' -> lifecycle events; 'what someone observed' -> condition assessment), and a prerequisite step ('Call list_assets first to resolve asset_id'). This is explicit routing guidance with named alternatives.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, covering the safety profile. The description adds useful context by naming the auth scope required, which is not in the annotations. Beyond that, no return format, rate limit, or side-effect details are provided.

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 waste, and the purpose 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 simple 2-parameter create tool with full schema coverage and annotations covering safety, the description covers purpose and scope. However, it omits any differentiation from the many similar comment-creation siblings, which is a meaningful gap given the dense toolset.

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 (comment and asset_id) are fully documented in the schema. The description adds no parameter-level meaning or format constraints beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb (Create) and resource (comment on an asset), making the core purpose clear. However, it does not distinguish this tool from similar siblings like create_infrastructure_asset_comment, create_project_comment, or create_work_order_comment, leaving the agent to infer scope from the tool 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?

The only guidance is the required scope 'asset_comments:write', which is a prerequisite rather than usage direction. There is no explicit when-to-use, when-not-to-use, or alternative sibling tool mentioned, so an agent gets no help choosing among the many create_*_comment 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 annotations already declaring readOnly=false, destructive=false and idempotent=false, the safety profile is covered. The description adds genuine value by disclosing the required write scope (asset_condition_assessments:write) and the point-in-time nature, but it omits the notable irreversible side effect (overwriting purchase cost via update_purchase_cost), which is disclosed only inside the schema.

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

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

Two tightly written sentences with the core purpose front-loaded and the prerequisite/auth details following. No filler, no restatement of the title.

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

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

For a create endpoint with 100% schema coverage and no output schema, the description covers the essential context: what it records, the required scope, and the prerequisite lookup. The one gap is that the description could flag that recording an assessment does not by itself change purchase cost, but the schema carries that detail.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters, including the detailed update_purchase_cost semantics. The description only adds a hint about resolving asset_id, which is marginal beyond what the parameter's own description provides, so the baseline 3 holds.

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 (Record) and resource (point-in-time condition assessment against an asset), which is more precise than a generic 'create assessment'. It implicitly separates itself from sibling creates like create_asset_cost or create_asset_status by naming the condition-assessment concept, though it never calls out those siblings directly.

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

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

Gives an explicit workflow prerequisite ('Call list_assets first to resolve asset_id') that tells the agent how to obtain a required input. It stops short of stating when NOT to use it or naming update_asset_condition_assessment as the alternative for editing an existing record.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent, closed-world write. The description adds the concrete auth requirement (asset_costs:write scope), which is genuinely beyond the annotations, but says nothing about duplicate handling or side effects like the purchase-order balance impact (that detail lives in the schema instead).

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, purpose front-loaded, scope requirement second, zero filler. 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 create tool with annotations present, a rich 100%-covered schema, and no output schema, the description covers purpose and authorization adequately. It stops short of any create-vs-alternative routing, which is the remaining gap.

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

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

Schema description coverage is 100%, so the 11 parameters including required fields, enum values, and the purchase_order_id balance semantics are already fully documented in the schema. The description contributes no additional parameter meaning, 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+resource ('Create a new asset cost entry') and disambiguates the record type by pointing at the AssetLab 'Expenses' page, which helps separate it from create_expense. It never names the closest sibling (create_infrastructure_asset_cost) explicitly, so differentiation is implied rather than stated.

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

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

The only usage guidance is the prerequisite 'Requires asset_costs:write scope'. There is no statement of when to choose this over create_expense, create_infrastructure_asset_cost, or update_asset_cost, leaving the agent to infer the boundary.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so safety profile is covered. The description adds two pieces of behavioral context annotations cannot convey: the required asset_documents:write scope and the ordering dependency on create_upload_url. Mentioning that repeated calls are non-idempotent would be a further improvement, but the added context is solid.

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 tight sentence plus a scope clause. The action is front-loaded, the prerequisite is parenthesized compactly, and 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 an 8-parameter mutation tool with no output schema, the description covers the two things an agent most needs that structured fields do not: the auth scope and the required upload-first workflow. Return-value behavior is not a gap since there is no output schema, but a note on non-idempotency or failure behavior would complete the picture.

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 8 parameters (name, asset_id, file_path, category, file_size, etc.) are already documented in the schema. The description only hints at file_path through the upload prerequisite and adds nothing about the enum category values or the optional fields. Baseline 3 is appropriate when the schema carries the load.

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 an asset document record') and distinguishes it implicitly from the many sibling document tools (create_project_document, create_contract_document, create_infrastructure_asset_document) by tying it to the asset entity. It does not explicitly name which sibling to use instead, but the 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?

It gives an explicit prerequisite workflow: the file must be uploaded first via create_upload_url, and the file_path argument depends on that response. That is clear contextual guidance for sequencing. It stops short of naming when-not to use it or alternative document tools, so not a 5.

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

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

Annotations already declare non-read-only, non-destructive, non-idempotent. The description adds value beyond that: the required asset_lifecycle_events:write scope (auth), the scope-resolution precedence rule (type strategy before type group), and the semantic boundary that replacement is not an event. It does not describe idempotency or duplicate-handling behavior, which is a minor gap for a create tool.

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

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

Front-loaded with the core action, then scope rules, then the replacement exclusion and the id-resolution workflow. Dense but every sentence carries information; the brief intervention examples add domain grounding without bloat. Slightly long, but justified by 17 params and a subtle domain model.

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 create tool with no output schema, the description supplies the scope model, auth requirement, precedence rule, and prerequisite lookups an agent needs before calling correctly, while the fully-covered schema handles field-level detail. Nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes further by explaining the 'exactly ONE of asset_type_id or asset_type_group_id' scope rule and its resolution order, which is the key selection decision for two otherwise-similar UUID params. It still leaves enum behaviors like work_generation to the schema.

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

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

States a specific verb+resource ('Create a facility lifecycle strategy event') and immediately disambiguates scope: events attach to an asset-type scope, never to individual assets, and names sibling-ish concepts (replacement, renewal forecast). An agent can tell this apart from create_infrastructure_lifecycle_event and update_asset_lifecycle_event.

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

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

Explicitly says what NOT to model (replacement), what TO model instead (recoats, retubes, overhauls), names the sibling tools to resolve type ids (list_asset_types / list_asset_type_groups), instructs to list existing events first to reuse a scope, and states the required write scope. When/when-not/alternatives are all present.

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

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

Annotations already declare this is a write (readOnlyHint=false), non-destructive, non-idempotent, and closed-world. The description adds the auth scope requirement, which is useful beyond annotations. It does not describe duplicate-handling or error behavior, but with annotations covering the safety profile, this is adequate.

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

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

Two sentences, front-loaded with the action and followed by the scope requirement. No wasted words; appropriately sized for the tool's simplicity.

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 association-creation tool with full schema coverage and descriptive annotations, the description covers the core purpose and auth scope. It does not explain behavior on duplicate associations (non-idempotent) or return values, but no output schema exists and annotations hint at the mutation nature. Largely complete.

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

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

Schema description coverage is 100%, with each parameter documented in the schema. The description adds no parameter-level meaning beyond what the schema provides, 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 'Link' and the resource pair 'part to an asset', and clarifies it creates an association. Differentiates well from create_part and create_asset, but does not explicitly distinguish from the analogous create_infrastructure_asset_part sibling.

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 action description implies usage, and the required scope (asset_parts:write) provides a prerequisite. However, there is no explicit when-to-use vs alternatives (e.g., update_asset_part, create_infrastructure_asset_part) or when-not guidance, leaving usage only implied.

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

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

Goes well beyond annotations: discloses UPSERT-by-asset_id, the one-placement-globally constraint, and the required asset_placements:write scope. The only nuance is that this upsert/re-move behavior reads close to idempotent while idempotentHint=false, though repeated calls with differing coordinates do still mutate state, so it is not a flat contradiction.

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

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

Three front-loaded sentences: action first, then the critical upsert semantics, then the bulk alternative and the auth prerequisite. No filler, every sentence carries required 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 write tool with no output schema, the description covers the operation, its uniqueness semantics, the scope prerequisite, and the bulk escape hatch. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so all six parameters are already documented (coordinates, source enum, region_id, uuid patterns). The description restates coordinate normalization but adds no parameter meaning beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ("Place an asset on a floorplan") plus the exact coordinate system, and the UPSERT semantics make it unmistakable from siblings like create_asset or update_asset_placement. 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 routes bulk scenarios to bulk_create with resource="asset-placements", and explains the repeat-call behavior (moves the pin rather than erroring). When-to-use and the alternative are both named.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, covering the safety profile. The description adds the required write scope ('asset_replacement_plans:write'), which is genuinely useful auth context beyond annotations, but says nothing about what happens on duplicate creation or failure 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 short sentences, front-loaded with the action and followed by the permission requirement. Nothing is wasted or buried.

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

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

For a 7-param mutation tool with no output schema, the description covers purpose and required scope but omits any return-value expectations, duplicate-handling, or failure behavior. Adequate but with clear gaps an agent might need.

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

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

Schema description coverage is 100% and all seven parameters (asset_id, planned_replacement_year, status, priority, estimated_cost, funding_source, notes) are documented in the schema itself. The description adds no parameter-level meaning beyond that, 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 ('Create') and resource ('asset replacement plan'), clearly distinct from the sibling create_asset, update_asset_replacement_plan, and delete_asset_replacement_plan. However it does not explicitly differentiate itself from alternatives the way a 5 would, relying on the unique resource 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?

No when-to-use context, prerequisites, or pointers to related tools (e.g., use update_asset_replacement_plan to modify an existing plan). The scope requirement is a permission note, not usage guidance about when this tool applies.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety and mutation profile is covered structurally. The description usefully adds the required asset_statuses:write scope, but omits meaningful behavior for a non-idempotent create, such as whether duplicate status names are rejected or silently duplicated.

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

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

Two compact sentences, front-loaded with the purpose and followed by the prerequisite. No redundant restatement of the title and nothing that could be trimmed 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?

With a fully documented schema and annotations covering the safety profile, the description is adequate for calling the tool. It leaves one real gap for a create tool flagged non-idempotent: no indication of uniqueness constraints on the status name or what happens on a duplicate submission.

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%: name, module (with its enum and default), and description are all documented in the schema itself. The description adds only the conceptual framing that a status is a lifecycle state, which does not extend parameter meaning. 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?

The description pairs a specific verb ('Create') with a precise resource ('asset status') and adds a clarifying gloss, 'lifecycle state for assets', which disambiguates it from the many other create_* tools. It does not explicitly name the update/delete/list counterparts, but the entity is specific enough that an agent can identify it without opening the schema.

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

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

The only usage-relevant information is the required write scope, which is a prerequisite rather than guidance. It never states when to use this tool versus update_asset_status (modifying an existing status) or list_asset_statuses (checking existing ones), so the agent must infer that this is for net-new statuses.

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

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

Annotations already disclose the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the bar is lower. The description usefully adds the required asset_types:write scope, which annotations do not cover. It says nothing about duplicate-name behavior or what the call returns, so it adds only modestly.

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, and the action statement is front-loaded ahead of the scope requirement. Nothing is wasted or buried.

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

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

For a simple create tool with full schema coverage and annotations that carry the safety profile, the core is covered. Missing are the duplicate-name outcome and the shape of the created resource, which the description could supply since no output schema exists.

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 all three parameters (name, group_id, description) documented in the schema itself. The description adds no parameter-level detail such as format or constraint hints beyond that, 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 immediately clear. It does not, however, distinguish itself from the closely named sibling create_asset_type_group, so an agent must infer the boundary. Clear purpose but 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?

No when-to-use guidance, no prerequisites beyond an implied scope, and no alternatives referenced. The agent gets no help deciding between this and create_asset_type_group or update_asset_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?

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the mutation/safety profile is covered. The description adds one genuine piece of context beyond them: the required asset_type_groups:write scope. It says nothing about duplicate-name behavior, validation failure, or what the 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 lead with the action, then the domain semantics, then the prerequisite. Every sentence earns its place and nothing is redundant with the title.

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

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

For a 3-param, no-output-schema create tool with rich annotations and full schema coverage, the description covers purpose, semantics, and the auth prerequisite. Only minor gaps remain, such as uniqueness constraints on the group name.

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

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

Schema description coverage is 100%, so name, color, and description are all documented in the schema with constraints (maxLength, hex example). The description adds no parameter-level detail beyond what the schema already provides, which is the baseline-3 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 a new asset type group") and adds domain meaning with "Groups organize asset types into logical categories," which distinguishes it conceptually from create_asset_type and create_system_group. It doesn't explicitly name a sibling it is not, 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?

Usage is implied by the create verb, and the "Requires asset_type_groups:write scope" line gives a real precondition. However, there is no explicit when-to-use guidance, no mention of the update_asset_type_group / delete_asset_type_group alternatives, and no note about what to do when a group already exists.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent write. The description adds auth context ('Requires attachments:write scope') not visible in structured fields, plus the single-parent invariant. It does not describe response shape or duplicate-handling, keeping it below a 5.

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

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

Two sentences, zero filler, with the linking scope front-loaded and the hard constraint and auth requirement following. 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 10-parameter mutation with full schema coverage and annotations carrying the safety profile, the description covers the two things structured data cannot: the single-parent rule and the required scope. It could optionally note whether the file must first be uploaded via create_upload_url, a minor gap.

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

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

Schema coverage is 100%, so per-parameter meaning is fully documented downstream (baseline 3). The description adds a genuine cross-parameter constraint — exactly one of work_order_id, work_request_id, pm_schedule_id, pm_template_id — that no individual schema property can express.

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

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

States a specific verb (Create) and resource (attachment record) and enumerates the four parent entity types it can link to. An agent can distinguish it from the numerous other create_* siblings 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?

Adds the meaningful constraint that exactly one parent ID must be supplied and names the required scope, which are genuine usage rules. However, it never says when to prefer this tool over related siblings such as create_upload_url, upload_file, create_asset_document, or update_attachment.

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

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

Annotations cover the safety profile (readOnly=false, idempotent=false, destructive=false), and the description adds genuinely non-obvious behavior: the auth scope needed, the 409 refusal on duplicate slots, and the fact that site_id/building_id are silently ignored. It does not describe the response shape, but with idempotentHint=false already declared, a duplicate submission failing is consistent and well-explained.

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

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

Purpose comes first, then auth, then the cardinality rule and the required fields — a sensible front-loading. It is dense and runs four sentences, but each sentence carries a distinct constraint; only the trailing 'Required:' restatement is partly redundant with 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 7-parameter mutation with no output schema and partial annotation coverage, the description supplies scope, conflict behavior, and the ignored-parameter caveat, which is most of what an agent needs. The only gap is that optional-vs-required for budgeted_amount and allocated_amount is muddled relative to 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 coverage is 100%, so the schema already documents every parameter and the baseline is 3; the description earns above baseline by explaining how module, site_id and building_id interact ('the tab does not read site_id or building_id'). Minor flaw: it lists budgeted_amount as Required while the schema requires 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?

The description states a concrete verb and resource ('Set an annual funding budget') and grounds it in a real-world referent ('as the dashboard Budget tab does'), which pins down the grain of the record. The specification of one figure per year, per funding source, per workspace distinguishes it from the nearby create_project_budget_item sibling without needing to name it.

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

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

It states the required scope ('budgets:write'), the exact cardinality rule ('Send one row per year and funding source'), an explicit prohibition ('do not split a year across sites or buildings'), and the failure mode if violated (409). An agent can decide whether this is the right tool and how to call it without trial and error.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive write. The description adds value beyond that: the required write scope and a cross-field validation rule (paired lat/long, one without the other is rejected) that would otherwise only surface as a runtime error.

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 the action, then the prerequisite, then the one non-obvious constraint. Nothing is padded and every sentence carries information.

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

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

For a create tool with no output schema, the description covers the action, the auth scope, and the key data-integrity constraint. It omits any note on required parent entities (e.g. that site_id must reference an existing site) or failure behavior, 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 nine parameters are documented in the schema, giving a baseline of 3. The description's lat/long pairing note duplicates what the schema already states in each parameter's description, so it adds no new semantic detail.

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

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

States a specific verb+resource ("Create a new building") which is immediately clear. However, it does no work to distinguish itself from the many sibling create_* tools, notably create_project_building and create_site, so an agent must infer which entity is which 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?

It surfaces a real precondition ("Requires buildings:write scope"), which tells the agent about an authorization gate. But it gives no guidance on when to use this versus create_project_building or create_site, and no exclusions, leaving usage largely implied.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the mutation profile is covered. The description adds the building_types:write scope requirement, which is genuinely useful auth context not present in any structured field, but nothing about duplicate names, failure modes, or return 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 short sentences, the action first and the prerequisite second. No filler, no redundancy.

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

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

For a simple two-parameter create with full schema coverage, no output schema, and annotations covering the safety profile, the description plus the scope note is close to sufficient. Only mildly short of a 5 given how little else the agent needs.

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

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

Schema coverage is 100% and both parameters carry their own descriptions (name required, maxLength bounds; description optional). The description adds nothing beyond the schema, 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 (Create) and resource (building type), which distinguishes it from nearby siblings like create_building, create_location_type, and create_asset_type. No explicit routing to alternatives, but the resource itself 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 when-to-use guidance, no statement of when to prefer bulk_create or update_building_type instead, and no preconditions beyond the scope note. 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the safety profile is structured. The description adds one genuinely useful non-schema fact, the required change_orders:write scope, but says nothing about whether duplicate co_number values are rejected, what happens to existing data, or the returned object.

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 no filler. It is tight, though the extreme brevity is arguably under-specification rather than disciplined conciseness given the 9-parameter surface.

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 9 params and no output schema, the minimum viable content is present (purpose + auth). However, nothing describes the created result or idempotency behavior around co_number, which an agent would want before calling.

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, the required set, and the status enum are documented in the schema itself. The description adds no parameter meaning, which is the correct baseline 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 a new change order") so the agent knows exactly what the tool does. The resource is distinct from siblings like create_work_order or create_purchase_order, but the description does no explicit sibling differentiation, relying on 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?

No when-to-use guidance, no prerequisites beyond the scope claim, and no mention of alternatives such as update_change_order or bulk_create. The agent is left to infer context entirely.

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

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

Annotations already declare the operation is non-read-only, non-destructive, and non-idempotent. The description usefully adds the required auth scope ('compliance:write'), which is real context beyond the structured fields, but says nothing about duplicate handling or what the non-idempotent behavior means in practice.

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, action first, with the scope requirement tacked on efficiently. 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 create tool with no output schema and six fully documented parameters, the description covers the essentials (what it makes, required scope) but omits what is returned (e.g., the new item's ID) and any constraints like duplicate-name behavior, leaving minor 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% with all six parameters documented in the schema, so baseline 3 applies. The description adds no parameter-level meaning beyond what the schema already provides.

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

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

States a specific verb and resource ('Create a new compliance item') and clarifies the domain with '(regulatory requirement)'. However, it does not differentiate from close siblings such as create_compliance_record or create_compliance_pm_schedule, which an agent could easily confuse it with given the large create_* family.

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 bulk_create, create_compliance_record, or the sibling compliance tools. The agent must infer usage context 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?

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the bar is lower. The description still adds value beyond structured data by disclosing the required auth scope (compliance:write) and the semantic effect on compliance status, though it says nothing about duplicate-link behavior or error conditions.

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

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

Front-loaded purpose followed by scope, required params, and a resolution tip in three tight sentences. The re-listing of required parameter names is mildly redundant with the schema, keeping it short of a full 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 non-idempotent mutation/link tool with annotations covering the safety hints and no output schema, the description covers auth scope, intended effect, and id resolution. It is nearly complete, though it could note what happens if the link already exists.

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 four parameters including weight (default 1) are already documented in the schema. The description merely re-lists the three required ids and gives a resolution hint, adding no syntax or semantic detail beyond what the schema provides. Baseline 3 is correct.

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

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

States a specific verb and resource with scope: 'Link a PM schedule to a compliance item, so completing the schedule keeps the item compliant.' This distinguishes it from sibling create_compliance_item and create_pm_schedule, making the junction/link semantics immediately 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?

Provides a prerequisite (compliance:write scope) and concrete setup guidance: 'Resolve both ids first with list_compliance_items and list_pm_schedules.' This tells the agent what to do before invoking, though it does not explicitly contrast this link-creation with the sibling create_* tools.

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

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

Annotations already declare the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false), so the bar is lower. The description adds a genuinely useful auth requirement (compliance_records:write), but says nothing about non-idempotency consequences, duplicate-record behavior, or side effects on related PM schedules.

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 permission requirement second. Efficient, though the parenthetical adds only marginal value and no usage routing is included.

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 seven-parameter mutation tool with five required FK-style references and no output schema, the description is thin. Permission scope is covered, but entity-resolution prerequisites and duplicate handling, which matter for a compliance audit trail, are absent.

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

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

Schema description coverage is 100%, so all seven parameters are already documented in the schema, including the five required ones. The description contributes no additional parameter meaning, which is the expected baseline 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+resource ('Create a new compliance record') and clarifies scope with the parenthetical 'audit trail entry'. It stops short of distinguishing itself from close siblings like create_compliance_item or create_compliance_pm_schedule, which share almost identical naming.

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 guidance offered is the required scope ('compliance_records:write'). There is no statement of when to use this versus create_compliance_item, create_compliance_pm_schedule, or bulk_create, nor any prerequisite about the referenced entities needing to exist first.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false). The description adds one genuinely useful behavioral fact not in the structured data — the contracts:write scope requirement — but says nothing about creation side effects or failure modes, so it is adequate rather than rich.

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

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

Two short sentences with zero filler, and the core purpose is front-loaded ahead of the scope constraint. It is efficient, though extremely terse for a 10-parameter tool.

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

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

With annotations covering the safety profile, a 100%-covered schema, and no output schema, the description covers the minimum an agent needs. It is missing sibling routing (update_contract, bulk_create, create_contract_site) that would make it complete for this crowded create_* namespace.

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 10 parameters (including the four required ones) are documented in the schema itself. The description adds no parameter 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+resource ('Create a new contract'), so the agent knows the operation is a create on the contract entity. It does not differentiate from siblings like create_contract_document or create_contract_site, so it falls 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 offers no when-to-use guidance, no prerequisites beyond the scope, and no routing to alternatives such as bulk_create or create_contract_site. The scope statement is an authorization requirement, not 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?

Annotations already disclose readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, covering the safety profile. The description adds the required scope, which is useful auth context beyond the annotations. It does not, however, describe side effects, what happens to related records, or any rate limits, so it adds moderate value but remains thin.

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 waste, and the core action is front-loaded before the permission note. Every sentence earns its place in this compact definition.

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

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

For a simple create operation with full schema coverage and relevant annotations, the description is minimally adequate. It states the action and the required scope, but omits the upload-first workflow context (which the schema mentions only for file_path) and any explanation of how this tool relates to create_upload_url. An agent can call it correctly from the schema, but the description does not enrich the overall context.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the input schema, including the note that file_path comes from an upload URL response. The description adds no parameter-level meaning beyond what the schema provides. A baseline of 3 is appropriate 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 states a specific verb and resource: 'Create a contract document record.' This clearly identifies the operation, and the agent can distinguish it from siblings like create_contract or create_project_document by resource alone. However, it does not explicitly differentiate from similar document-creation tools, so it falls 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 only guidance is a prerequisite: 'Requires contract_documents:write scope.' There is no statement of when to use this tool versus alternatives such as update_contract_document, bulk_create, or create_upload_url. An agent gets the permission requirement but no routing logic or context for selecting this tool over siblings.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the agent knows this is a non-idempotent write. The description adds the OAuth scope requirement, which the annotations do not cover. It does not, however, explain what happens on a duplicate assignment, which is the key behavioral question for a non-idempotent create.

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: the action is front-loaded and the prerequisite follows. 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 simple two-parameter join-table create with no output schema and annotations covering the safety profile, the definition covers what the agent needs to invoke it, including the scope prerequisite. The only gap is duplicate-assignment behavior, which is minor but relevant given idempotentHint=false.

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 UUID parameters, both documented with format and pattern in the schema. The description adds no format, source, or constraint detail beyond the schema, 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 and resource: 'Assign a contract to a site.' This clearly distinguishes it from create_contract (which creates the contract itself) and create_site. However, it does not differentiate from analogous join-table siblings such as create_service_area_site or create_project_site, which use the same assignment pattern.

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 supplies a required-privilege prerequisite ('Requires contract_sites:write scope'), which is useful context for invocation. But it gives no when-to-use guidance relative to alternatives like list_contract_sites or delete_contract_site, and no note about whether the contract/site must already exist.

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

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

Annotations already declare readOnly=false, idempotent=false, destructive=false and openWorld=false, so safety is covered. The description adds a genuinely useful piece of information the annotations lack: the required write scope. It does not disclose whether name must be unique, whether the new category is returned, or what happens on duplicates.

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 action stated first and the permission requirement second. Nothing could be trimmed 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 three-parameter create tool with full schema coverage and no output schema, this is close to sufficient. The remaining gap is that it never says how the created category is identified in the response or how it relates to the sibling bulk_create.

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% – name, is_active and parent_id are each documented in the schema with type, constraints and format. The description adds no parameter 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?

Specific verb+resource ("Create a new cost category") that matches the name exactly and is unambiguous against siblings like update_cost_category or delete_cost_category. It does not, however, differentiate itself from bulk_create, which is the one sibling that could plausibly be confused with it.

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?

"Requires cost_categories:write scope" is a prerequisite, not usage guidance. There is no statement of when to use this versus bulk_create, or when to prefer update_cost_category for an existing category. The agent gets a permission note but no selection criteria.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds real behavioral context beyond them: the conflict behavior on duplicate tiers (409), the required write scope, and the semantic direction of the modifier (below 1 tightens, above 1 relaxes) plus the built-in defaults a missing row falls back to.

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 sentences, each carrying distinct load: purpose, override/default semantics, effect direction, conflict handling and required scope. Purpose is front-loaded and no sentence is padding.

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

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

For a two-parameter create tool with no output schema, the description covers everything an agent needs to call it correctly: what it writes, the fallback behavior, the numeric range semantics, the duplicate-tier failure mode and its remedy, and the permission requirement.

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 description earns a bump by supplying the built-in default values per tier (critical 0.6, high 0.8, medium 1.0, low 1.4) and restating the multiplier's directional effect, which helps interpret the numeric modifier in context. It does not add formatting or unit detail beyond that.

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 for one tier') and immediately clarifies that rows are overrides rather than defaults, which distinguishes it from get/list/update/delete_criticality_modifier siblings. The per-tier default table makes the tool's role unambiguous.

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

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

Explicitly routes the agent: 'One override per tier; a duplicate returns 409, so call list_criticality_modifiers and update the existing row instead.' It also states the prerequisite scope (los_targets:write). This is exactly the when-to-use/when-not-to-use/alternative 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false. The description adds the required auth scope ('custom_fields:write'), which is useful context beyond annotations, but it does not describe return behavior, side effects, or duplicate handling.

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. Every sentence earns its place and there is no waste.

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

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

The description covers purpose and authorization for a create tool with rich schema coverage and useful annotations. However, it does not mention what the tool returns (no output schema exists), nor does it clarify valid entity_type values or field_options behavior, leaving some invocation context to 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%, so the schema already documents all seven parameters, including the field_type enum. The description adds no additional parameter meaning beyond what the schema provides, 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 and resource: 'Create a new custom field definition.' This clearly distinguishes it from sibling tools such as create_custom_field_value (different resource) and update/delete_custom_field_definition (different verb), even without naming them explicitly.

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

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

Implies usage by saying it creates a 'new' definition and provides a prerequisite ('Requires custom_fields:write scope'), but it does not state when to use this versus update_custom_field_definition or bulk_create, nor does it give exclusions. Guidance is present but incomplete.

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

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

Annotations declare idempotentHint=false, but the description asserts 'Writes upsert on (entity_id, field_definition_id) so replaying a batch is idempotent' - a direct conflict with the structured hint. The useful side information (custom_fields:write scope required, upsert key) does not offset the contradiction, which can lead an agent to retry assumptions that the annotation forbids.

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 purpose, then typing guidance, then idempotency and scope. Dense but every sentence carries operational information; no restating of the title.

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

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

For a 7-parameter mutation with no output schema, the description covers purpose, parameter strategy, idempotency intent, and required scope, which is near-complete. The only gap is routing versus the sibling update/delete tools, and the idempotency claim conflicts with the annotations rather than completing them.

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 per-column semantics are already documented; the description goes beyond that by explaining the dispatch strategy (typed columns preferred, single `value` shim dispatched by field_type) and that `value` is ignored when a typed column is set. This adds selection guidance the schema alone 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 and resource ('Create (upsert) a custom field value for an entity') and the '(upsert)' qualifier immediately distinguishes it from the plain update/delete siblings in the custom-field family. 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?

Gives strong guidance on which parameter shape to prefer ('prefer setting the one that matches the field definition's field_type') and explains the legacy `value` shim, which is useful. However, it never states when to call this tool versus update_custom_field_value or delete_custom_field_value, so routing against the closest siblings is left to inference.

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

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

Annotations already declare the full safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the description is not the primary source of behavioral context. It does add a useful fact beyond the annotations: the required expenses:write scope. It does not mention that repeated calls create duplicate records, but the non-idempotent annotation covers that.

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, and the operation is front-loaded before the scope requirement. 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 create tool with 8 parameters and no output schema, the definition is minimally adequate: the schema covers inputs and annotations cover safety. It does not describe what the call returns or confirm the created resource's handling, leaving a modest gap.

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

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

Schema description coverage is 100% across all 8 parameters, so the schema fully documents each field and its required/format constraints. The description adds no parameter-level meaning beyond what the schema already provides, 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?

The description names a specific verb and resource ('Create a new expense'), so the agent knows exactly what operation it performs. However, it offers no differentiation from near-identical siblings such as bulk_create or the other create_* tools, so it does not reach the top of the scale.

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 statement of when to use this tool versus alternatives like bulk_create or update_expense. The only guidance is the required scope, which is a prerequisite rather than a when-to-use rule.

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

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

Annotations already declare the safety profile (not read-only, not destructive, not idempotent, closed-world), so the bar is lower. The description adds a genuinely useful behavioral fact the annotations lack: it requires the 'floorplans:write' scope, and it states the exactly-one-of constraint that governs valid invocations.

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 sentences, front-loaded with the action and the key constraint, then usage context and scope. No redundancy, and every sentence carries distinct information.

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

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

For a mutation tool with full schema coverage and annotations but no output schema, the description is largely complete: it covers the action, the input constraint, auth scope, and calling context. It does not mention return behavior or idempotency implications, which would round it out.

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 mutual-exclusivity rule ('Provide EXACTLY ONE of building_id or site_id') that the schema only implies per-field, which is a real semantic gain over the 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?

The description opens with a specific verb+resource ('Create a floorplan row') and immediately clarifies the scoping model (per-building vs site-level). It is clearly distinguishable from siblings like create_building or create_floorplan_region, though it does not explicitly name a sibling it contrasts against.

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?

Strong when/when-not guidance: it explains the web app calls this per PDF page and that MCP clients 'rarely need to call this directly' since they don't upload the PDF, which steers the agent away from misuse. It stops short of naming a specific alternative tool to use instead.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the mutation profile needs no repeating. The description adds genuinely new context: a required authorization scope (floorplan_regions:write) and the coordinate convention (normalized 0-1, origin top-left) that governs how the polygon must be authored. It does not mention that repeat calls produce duplicate regions, but that is a minor 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?

Three compact sentences with no filler; the core action is front-loaded and the coordinate constraint and linking option follow in priority order, with the scope requirement last.

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

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

For a 7-parameter create tool with full schema coverage and a clear annotation profile, the description covers the essentials an agent needs to author a valid call. It omits what is returned (e.g. the new region ID), which is acceptable given there is no output schema but would still have been useful for chaining.

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, establishing a baseline of 3. The description restates polygon normalization and clarifies that location_id must point to an existing Location, adding a little meaning but not going beyond the schema's own guidance.

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

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

States a specific verb and resource ("Create a region") and disambiguates the noun with "(labeled room or zone) on a floorplan," so the agent can distinguish it from create_floorplan or update_floorplan_region without opening a schema.

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

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

Gives clear context: regions are created against an existing floorplan and may optionally be linked to an existing Location, plus the required write scope. It does not state when not to use it or point to siblings (e.g. bulk_create, update_floorplan_region), but the usage conditions are otherwise clear.

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

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

Beyond the annotations, the description discloses important behavior: questions are snapshotted at attach time so later template edits do not affect in-progress forms. It also states the required form_responses:write scope and clarifies what this API does not do.

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

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

The description is front-loaded with the core purpose and then adds the snapshot behavior, alternative, limitation, and required scope. Every sentence earns its place and none 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 create/attach tool with no output schema, the description is complete enough to guide correct selection and invocation. It covers the main alternative pattern, the snapshot semantics, the non-API workflow boundary, and the required scope.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, including how to resolve template_id and subject_id. The description largely reinforces the same concepts rather than adding new parameter-specific syntax or constraints.

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

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

The description states a specific action and resource: attaching a published form to one record so it can be filled in. It also distinguishes this from the PM-schedule bulk approach, which is the relevant sibling behavior in the create-family ecosystem.

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

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

It gives explicit use guidance: use this for one existing record, and instead set form_template_id on a PM schedule when the form should be generated for every work order. It also clarifies that answering and completing the form happen outside this API.

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

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

Annotations already declare the safety profile (readOnly=false, destructive=false, idempotent=false). The description adds real context beyond them: it requires form_templates:write scope, defaults to draft status, and warns that publishing is rejected if any question is malformed. It does not say what the response returns, which matters for chaining to step 2.

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

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

Front-loaded with the core action and immediately followed by the workflow steps; no filler sentences. It is a dense single paragraph, but every clause (definition, sequencing, validation constraint, scope) carries information.

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

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

Covers creation, the downstream steps needed to make a usable form, the auth requirement, and the publish validation rule, with no output schema left unexplained. The one omission is that it never states the created template id is returned, which the agent needs to call create_form_template_item next.

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, including enums and the work_category_id lookup hint. The description reinforces the draft-vs-published semantics for status but adds no new parameter-level detail, 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 and defines what a form template is (reusable inspection/checklist/compliance/survey definition). It also positions itself in the workflow relative to create_form_template_item and update_form_template, so an agent can distinguish it from its nearest 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?

Explicit sequencing: 'Step 1 of building a form', draft first, then add questions via create_form_template_item or bulk_create on form-template-items, then publish via update_form_template status=published. It names the alternatives and the condition that selects each, which is exactly the when-to-use guidance needed.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so safety profile is covered. The description adds the required 'form_template_items:write' scope and implies sequential ordering, which are useful behavioral details beyond annotations. It does not cover return values, but no output schema exists so that is less critical.

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 each sentence adds distinct value: the first states the purpose, the second gives the usage pattern and alternative. 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?

Given ten parameters, nested objects, full schema coverage, and annotations covering safety, the description provides enough to select and invoke the tool correctly. It misses minor details like return behavior or error cases, but these are not essential here. The scope requirement and alternative usage cover the main contextual needs.

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

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

Schema description coverage is 100%, so all ten parameters are thoroughly documented in the input schema. The description only adds the notion of calling 'in order', which overlaps with the schema's sort_order description. It does not add syntax or constraints beyond what the schema already provides.

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

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

The description states a specific verb and resource: 'Add one question (item) to a form template.' It distinguishes this tool from the bulk alternative by naming 'bulk_create on form-template-items' and clarifies the one-per-call pattern. An agent can confidently select it over other 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?

The description explicitly says to use this tool once per question in order, and names the alternative bulk_create for adding multiple items. It also states the required write scope, which is a prerequisite. This gives clear when-to-use and when-to-use-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?

Annotations already declare this is a non-destructive, non-idempotent write. The description adds genuinely useful behavior beyond that: required GeoJSON type per feature_type, EPSG:4326 with [lon, lat] ordering, server-side computation of length_m/slope_pct/risk_score, and the required infrastructure_assets:write scope.

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 verb and resource; the geometry/CRS constraint and the server-computed fields follow without filler. Every clause carries actionable 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 56-parameter mutation with no output schema, the description covers the highest-risk details (geometry shape, coordinate convention, computed fields, auth scope). It is nearly complete; a note on what the created asset returns would close the remaining gap.

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

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

Schema coverage is already 95%, so the baseline is 3. The description nevertheless adds meaning the schema does not: coordinate order, CRS, the Point/LineString-to-feature_type mapping, and the fact that length_m, slope_pct, and risk_score are derived server-side rather than supplied.

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 clarifies the two sub-shapes it covers ("feature - segment or node"). It is clear what the tool does, but it does not explicitly distinguish itself from close siblings like create_asset or 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 gives no when-to-use guidance and names no alternatives, despite a crowded sibling set (create_asset, bulk_create, create_infrastructure_network). An agent must infer from the name alone whether this is the right creation tool.

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

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

With annotations covering the safety profile (readOnly/ destructive/ idempotent hints), the description adds real context the annotations lack: the author is auto-attributed to the API key, user_id must not be passed, and the call requires infrastructure_asset_comments:write scope. This is exactly the extra behavioral disclosure that earns credit on top of 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 tight sentences with the purpose front-loaded and the constraints second. No filler, though it stops just short of being maximally 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 simple two-parameter create tool with no output schema, the description covers purpose, auth scope, and attribution behavior adequately. An agent could invoke it correctly; the only gap is sibling disambiguation, 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% and both parameters are already documented, so the baseline is 3. The description clarifies that authorship is implicit (do not pass user_id), which is useful but concerns a field that does not exist in the schema rather than adding meaning to comment or feature_id.

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

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

States a specific verb ("Add") and resource ("comment to an infrastructure feature"), so the operation is unambiguous. It implies the target is an infrastructure feature rather than a generic asset, but it does not name the sibling comment tools (create_asset_comment, create_project_comment, create_work_order_comment) to sharpen the boundary.

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

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

The description says what the tool does but gives no when-to-use / when-not guidance and does not point to any alternative among the closely related comment-creation siblings. The scope note is a prerequisite, not usage routing.

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

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

Annotations already declare this as a non-read-only, non-destructive, non-idempotent write, and the description usefully adds two things annotations cannot express: the required infrastructure_asset_costs:write scope and the fact that work_order_number is derived server-side from work_order_id. It does not disclose duplicate/retry behavior, which matters given idempotentHint=false, but the added auth and derivation context is real value.

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 with the core purpose front-loaded and no filler; each sentence carries a distinct constraint. The work_order_number sentence is slightly puzzling since that field is absent from the schema, costing a point on clarity but not on length.

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

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

For a write tool with 8 parameters, 4 required, no output schema, and a full schema description, the description covers what the tool does, its scope requirement, and one derived-field caveat. It omits what happens on repeat calls (relevant given idempotentHint=false), whether feature_id must pre-exist, and any post-creation effect such as the cost counting against a purchase order balance.

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 and the schema already documents all 8 parameters, including purchase_order_id's balance implications. The description clears that baseline by warning the agent not to set work_order_number (a server-derived field), which is a constraint the schema does not carry.

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: "Record a cost against an infrastructure feature." That is unambiguous about what gets written. It does not, however, distinguish this tool from the closely named sibling create_asset_cost, leaving the agent to infer the entity 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 or when-not-to-use guidance and no named alternative, despite create_asset_cost and create_expense existing as plausible near-neighbors. The only routing-ish information is an implicit scope statement (infrastructure features), which the agent must infer rather than being told.

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

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

Annotations already state this is a non-read-only, non-destructive, non-idempotent write. The description adds the write scope requirement (infrastructure_asset_documents:write) and the upload dependency, which are useful auth/workflow context beyond the annotations. It does not cover failure modes or response 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?

Three tight sentences, front-loaded with the purpose, then the workflow, then 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?

For a create tool with no output schema, the description covers purpose, prerequisite workflow, and auth scope, which is nearly all an agent needs. It stops short of describing the return value or post-create behavior, but annotations and schema carry the rest.

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 that file_path comes from create_upload_url. The description's mention of file_path merely repeats the schema rather than adding format or validation semantics, 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 ("Attach document metadata to an infrastructure feature"), which is enough to tell it apart from sibling document tools like create_asset_document and create_project_document by attachment target. It stops short of naming those alternatives explicitly, so it is clear but not fully sibling-differentiated.

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 sequence: upload bytes via create_upload_url first, then pass the returned file_path here. That is strong when-to-use guidance, though it names no when-not conditions or alternative document tools.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the mutation profile is covered. The description adds one genuinely useful behavioral fact beyond the annotations: the required infrastructure_asset_inspections:write scope for authorization. It says nothing about duplicate handling or validations.

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 authorization constraint follows. 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?

For an 8-parameter mutation tool with a nested defects object and no output schema, the description is minimal but adequate given full schema coverage and explicit annotations. It omits any mention of what is returned or validation behavior, which is a gap but not a blocking one.

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, including nested defect observations and the 0-100 condition score range. The description adds no parameter-level detail, 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?

The description states a specific verb and resource ('Record an inspection against an infrastructure feature'), which clearly identifies the operation. It does not explicitly distinguish itself from close siblings like create_infrastructure_asset_comment or update_infrastructure_asset_inspection, but the verb+resource pairing 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 gives no when-to-use or when-not-to-use guidance and names no alternatives, which matters in an API with hundreds of near-identical create_* siblings. The scope requirement is a prerequisite, not usage routing.

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

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

Goes beyond the annotations by disclosing the composite uniqueness rule on (feature_id, part_id), the concrete failure mode (409 on duplicate), and the required infrastructure_asset_parts:write scope. Annotations only supply the generic non-read-only, non-idempotent, non-destructive profile; the description adds the operational constraints an agent needs before calling.

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 auth requirement following in decreasing order of importance. Every clause carries information.

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

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

Covers action, key constraint, error behavior, and auth scope for a three-parameter write tool, with no output schema to explain. The return payload on success is unstated, a minor gap for an operation whose annotations already flag it as non-idempotent.

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 documents each field individually, so the baseline is 3. The description adds relational semantics the schema lacks: that feature_id and part_id form a unique pair, which affects how an agent should sequence calls before retrying.

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 pair ('Associate a part with an infrastructure feature'), which is unambiguous on its own. It does not distinguish itself from the near-identical sibling create_asset_part, nor from update_infrastructure_asset_part, leaving the agent to infer which entity type 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?

Usage is implied by the verb and the required identifiers, but there is no explicit when-to-use guidance, no mention of the non-infrastructure counterpart create_asset_part, and no pointer to update_/delete_/bulk_ variants for related operations. Minimum viable routing information.

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

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

Annotations cover the mutation safety profile (readOnly=false, destructive=false, idempotent=false). The description adds value beyond them: the write scope required for authorization and the fact that is_builtin is force-set to false — a behavioral detail not present in the schema at all.

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, zero filler. The purpose is front-loaded and the builtin caveat follows immediately after it 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 operation with full schema coverage and annotations present, the description supplies the two things structured fields lack: the required scope and the forced is_builtin=false behavior. It does not mention non-idempotency/duplicate-code handling, a minor gap given no output schema.

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

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

Schema description coverage is 100% across all 6 parameters (code pattern, category enum, lengths), so the schema carries parameter semantics. The description adds no field-level detail, 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?

The description gives a specific verb+resource ('Create a tenant-defined infrastructure feature class') and immediately bounds scope by excluding AssetLab-managed builtins. It does not name a sibling tool to differentiate from, so it lands at clear-but-unrouted rather than 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?

It states an explicit when-not: builtin classes cannot be created via API, and names the required scope (infrastructure_feature_classes:write). It gives no guidance on adjacent sibling choices such as create_infrastructure_asset or create_system_class, but the exclusion plus scope requirement is solid 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?

Annotations only provide the generic write profile (readOnly=false, destructive=false, idempotent=false), so the description carries real added weight: it discloses the required infrastructure_lifecycle_events:write scope and the scope-resolution rule that every feature resolves the most specific matching scope. It does not state whether the created event is returned or how duplicates are handled.

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

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

Front-loaded with the action, then scope semantics, then the replacement exclusion, then the operational hint and auth scope. Every sentence carries information, though the paragraph is dense and the replacement tangent could be tightened.

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

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

Covers auth requirements, scope modeling, and domain exclusions for a 20-parameter non-idempotent create. With no output schema, the only real gap is not saying what comes back (e.g. the created event id), which is a minor omission rather than a blocker.

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

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

Schema coverage is 100% with rich per-field descriptions, so the baseline is 3, but the description adds meaning on how feature_class, material, and the diameter band combine into a scope and how specificity resolves. That goes beyond restating field docs and helps an agent choose scope parameters correctly.

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 lifecycle strategy event') and immediately scopes what the resource is: strategy/scope-level, not per-asset. The 'never to individual features' clause implicitly distinguishes it from sibling create_asset_lifecycle_event, so an agent can pick the right tool without opening schemas.

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

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

Gives concrete operational guidance: list existing events first to reuse a scope, and model pre-replacement interventions (crack sealing, relining, resurfacing) rather than replacement. It stops short of naming the sibling that handles replacement/asset-level events, so the alternative is implied rather than explicit.

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