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

Beyond annotations (only destructiveHint: false), the description discloses important behavior: this commits a regulated record, it is dry-run by default, and confirm:true is required to execute. The final 'Write' clarifies that this is a mutating call despite the non-destructive hint. It could add more about side effects or failed dry-runs, but the core behavioral traits are clearly stated.

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

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

The description is compact and front-loaded with the main purpose, followed by the required-contact rule and the dry-run/confirm behavior. The final standalone 'Write.' is slightly redundant, but the overall description is efficient and every substantive sentence serves a clear purpose.

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

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

For a complex tool with 15 parameters, nested objects, and no output schema, the description covers the most critical operational facts: what the tool does, the mandatory contact requirement, and the dry-run default. It doesn't describe response formats or edge-case behavior, but an agent has enough context to select the tool and invoke it safely without unintended commits.

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

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

Schema coverage is 67%, so the schema covers most parameters, but the description adds high-value meaning by explaining that a supplier contact is REQUIRED and enumerating the three acceptable ways to provide it (contactId, contactExternalId, or inline contact). It also reinforces the confirm parameter's crucial role in executing vs. previewing, which helps the agent avoid an unintended commit.

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

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

The description uses a specific verb-resource pairing: 'Record an acquisition and commit it to the A&D book in one step.' It clearly names the combined create+commit behavior and calls it the 'recommended intake path,' which distinguishes it from siblings like create_pending_acquisition and commit_acquisition.

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

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

The description gives explicit context for use: it is the recommended one-step path and requires a supplier contact via contactId, contactExternalId, or an inline contact. It also explains the dry-run vs. execute flow with confirm:true. It doesn't explicitly name when to prefer the separate pending/commit siblings, but the 'one step' recommendation makes the intended use 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?

The description adds behavioral context beyond the sparse annotations by stating 'Executes directly' and 'Write,' making the mutating, immediate nature of the call explicit. It does not contradict the destructiveHint=false annotation, though it stops short of explaining reversibility or side effects.

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 extremely concise and front-loaded with the core action, followed by the key timing/behavioral detail. The final 'Write.' is terse but meaningful given the absence of a readOnly annotation.

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

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

For a mutating call with 22 parameters, no output schema, and minimal annotations, the description is too thin. It omits return value expectations, failure/validation cues, how repeated calls behave, and how this step fits into the overall acquisition lifecycle beyond 'uncommitted.'

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

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

The description provides no parameter-level information beyond what the schema already has. With 22 parameters and only 50% schema description coverage, many optional fields such as cost, totalLength, barrelLength, and countryOfManufacture remain undocumented in both the schema and the description.

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

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

The description clearly states the action ('Add a single firearm') and the target resource ('a pending acquisition'). It is immediately distinguishable from siblings like create_pending_acquisition or commit_acquisition, and the singular 'single firearm' adds precision.

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 clear usage context by specifying the operation is for a 'pending acquisition' that is 'still uncommitted,' which implies use before commit. However, it does not explicitly list when not to use it or point to alternatives such as update_acquisition_item.

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 destructiveHint=false, leaving the description to convey that this is a mutating call; 'Executes directly. Write.' does communicate an immediate side effect rather than a dry run. It does not disclose duplicate-item behavior, effects on disposition totals, or reversibility beyond the existence of a sibling remove tool, but the basic write nature is stated.

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

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

The description is short, front-loaded, and scannable, with the core function in the first sentence. 'Write.' is somewhat redundant with 'Add' and 'Executes directly.' is arguably unnecessary, so a couple of words do not earn their place, but the overall structure is still 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 four-parameter mutation with no output schema and sparse annotations, this is minimally workable: it identifies the target disposition state, item identifier, and optional price. Missing are lifecycle context such as requiring a pending disposition created by create_pending_disposition and the eventual need to commit_disposition, plus any error or duplicate-item behavior.

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 structured schema already documents all four parameters. The description's 'by GUID, optionally with a price' adds only lightweight context that mirrors the schema's id and price descriptions rather than meaningfully enhancing them.

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

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

States a specific verb and resource: 'Add inventory items (by GUID, optionally with a price) to a pending disposition.' The pending-disposition qualifier and item/price detail clearly distinguish it from related disposition tools such as dispose, create_pending_disposition, and remove_disposition_items.

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 phrase 'to a pending disposition' implies this is for draft dispositions and not committed ones, giving some usage context. However, no alternatives are named and there is no explicit when-not-to-use guidance, so the agent must infer the lifecycle relationship to commit_disposition and remove_disposition_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 provide idempotentHint=true and destructiveHint=false. The description adds useful behavioral context with 'Executes directly' and 'Write', indicating immediate mutation with no confirmation step. It does not contradict the annotations, though it stops short of describing side effects like replacing an existing contact attachment.

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 extremely economical: a front-loaded purpose sentence followed by two short behavioral clauses, with no filler or redundant restatement. Every sentence contributes either to intent or execution semantics.

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

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

Given the tool's simplicity, complete schema coverage, and annotations covering idempotency and safety, the description is nearly sufficient for an agent to invoke it correctly. It does not describe return values or edge cases like pre-existing contact attachments, but those are minor gaps for this operation.

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

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

Schema description coverage is 100%, with the schema already documenting id, contactId, account, and auditUser semantics. The description adds no parameter-specific detail beyond the schema, so the baseline score 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?

States the specific operation (assign), the object (existing supplier contact), and the target resource (pending acquisition), which clearly distinguishes it from sibling tools like attach_disposition_contact or set_item_acquisition_contact. The verb+resource combination leaves little ambiguity about what the tool does.

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 phrase 'existing supplier contact' and 'pending acquisition' implies when to use the tool and a boundary (do not create a contact; acquisition must not yet be committed). However, it never explicitly names alternatives such as create_contact or attach_disposition_contact, nor states when not to use it, so the guidance remains mostly implicit.

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

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

Annotations already provide idempotentHint=true and destructiveHint=false. The description adds 'Executes directly' and 'Write', signaling immediate mutation. It does not disclose what happens if the disposition is already committed, whether a previously attached contact is replaced, 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?

The main sentence is front-loaded and precise, and the two short supplements are minimal. 'Write' is slightly redundant with 'Assign', but the overall description is tight and easy to parse.

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 fully documented parameters and annotations covering safety/idempotency, the core operation is well specified. However, there is no output schema and the description omits return values, failure modes, and behavior when the disposition is not pending, leaving some ambiguity for an agent invoking the tool standalone.

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 even without parameter details in the description. The phrase 'recipient/buyer' adds a small semantic clarification to contactId, but the schema already documents the core role of both parameters.

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

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

Description uses a specific verb 'Assign' with a clear resource ('existing recipient/buyer contact') and target ('pending disposition'), making the operation unmistakable. It also distinguishes itself from the similar sibling attach_acquisition_contact by anchoring on dispositions.

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?

'Pending disposition' gives a clear precondition: the disposition must not yet be committed. 'Existing recipient/buyer contact' implies the contact should be created beforehand. It does not explicitly name alternatives like attach_acquisition_contact or create_contact, but the context is clear enough for selection.

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

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

Annotations already provide idempotentHint and destructiveHint, and the description reinforces the write nature with 'Write.' It adds that items are 'marked as physically verified' and that location may be updated, which is useful. However, it does not disclose potential side effects such as audit trail impact, rollback behavior, or what happens on partial failure.

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

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

The description is compact and front-loads the core action. The one-word sentence 'Write.' is somewhat redundant with 'Mark' but reinforces behavioral intent without adding bulk. It is appropriately sized and easy to scan.

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 operation is a bulk write with 7 parameters and no output schema, so the description carries responsibility for orienting the agent. It explains the primary use and optional location change but omits guidance on batch failure, return values, or how auditUser and verifiedUtc fit into the orchestration. The schema covers parameter details, but the overall context is only moderately complete.

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

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

Schema description coverage is 100%, so the schema already documents every parameter. The description adds value by mapping 'list of serial numbers' to serials and 'optionally updating their location' to updateLocation/location, but it does not add semantic meaning for the remaining parameters. 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 names a specific verb ('Mark'), a specific resource ('a list of serial numbers'), and a concrete business context ('during a cycle count'). It also mentions the optional location update, which distinguishes this from generic update_item or search tools. It clearly differentiates from sibling tools by focusing on physical verification rather than acquisition, disposition, or general updates.

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 phrase 'during a cycle count' implies a clear use context, but the description does not explicitly say when not to use this tool or how it compares to alternatives like update_item. There is no mention of exclusions or sibling routing, so the agent must infer applicability.

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

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

The description goes well beyond the minimal destructiveHint=false annotation by revealing that the call is a write, is irreversible ('point of no return'), and—critically—does nothing by default, requiring confirm:true to execute. This is exactly the kind of behavior an agent needs to know before calling. It does not detail post-commit side effects, but the core behavior is well covered.

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, with the core purpose and the most important safety behavior ('dry-run by default', 'confirm:true') front-loaded. No fluff or repeated schema content.

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

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

For a four-parameter tool with no output schema, the description provides the key usage context: what it commits, that it is irreversible, and how to make it actually run. It could mention the expected return value or prerequisite state of the acquisition, but these gaps are minor given the excellent schema coverage.

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 fully documents id, account, confirm, and auditUser. The description adds no new parameter-level meaning; it merely restates the confirm semantics that 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 ('Commit'), an unambiguous object ('a pending acquisition'), and the destination ('the A&D book'). This clearly distinguishes it from siblings such as commit_disposition and create_pending_acquisition, even without naming them.

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

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

The phrase 'commit a pending acquisition to the A&D book' implies it should be used when finalizing an already-created pending acquisition, and the dry-run warning clarifies how to invoke. However, it does not explicitly state when to use this instead of update_acquisition, delete_acquisition, or create_pending_acquisition, nor when not to use it.

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

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

Beyond the sparse annotations, the description discloses irreversibility, the dry-run safety default, the confirm gate, and consequential side effects such as Multiple Sale reports and auto-created FFL recipient acquisitions. This is exactly the behavioral context an agent needs before invoking a write operation.

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

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

Three short sentences front-load the purpose and risk, then side effects, then the execution requirement. The final 'Write.' is a concise mutation cue that earns its place given the otherwise sparse annotations.

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

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

For a mutating tool with no output schema, it covers the decision-critical facts: default no-op behavior, how to execute, and what side effects may result. Account selection and audit-user mechanics are left to the schema, which is acceptable because schema coverage is complete.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds value by explaining the confirm flag's dry-run behavior and causally linking FFL transfer side effects to the transfer-emails concept, which goes beyond the bare schema descriptions.

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

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

The description uses a specific verb and resource — 'Commit a pending disposition to the A&D book' — and reinforces it with 'the point of no return.' This distinguishes it clearly from staging tools like create_pending_disposition and read-only disposition tools.

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

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

It clearly frames this tool as the finalizing step for pending dispositions and gives concrete execution guidance: dry-run by default, pass confirm:true to actually commit. It does not explicitly name alternatives or exclusions, but the context is unambiguous enough for an agent to select it correctly.

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 destructiveHint=false, so the description carries most of the behavioral burden. It discloses that this is a write operation, executes directly outside A&D records, and that existing-contact matches are reported via headers. It does not cover authentication, error behavior, or response body contents, but the main behavioral caveats are present.

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

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

The description is compact, front-loaded, and easy to parse. The trailing 'Write.' is redundant since 'Create' already implies mutation, but it is brief enough not to significantly hurt clarity.

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

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

For a tool with 26 optional parameters, no output schema, and low schema coverage, the description gives a usable selection rule but leaves many parameters and the exact response shape unexplained. The duplicate-match header note is useful, but an agent would still need more information to handle advanced or edge cases confidently.

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

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

Schema description coverage is only 35%, and the description partially compensates by mapping fflNumber, organizationName, and first/last name to their contact types and pointing to premise address fields. However, most of the 26 parameters (fax, sotein, businessType, suffix, etc.) remain unexplained, so the description does not fully cover the parameter semantics gap.

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

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

The description opens with a specific verb and resource ('Create a contact') and immediately enumerates the three supported subtypes (FFL, organization, individual). The clarifying statement that a contact is not an A&D record also helps distinguish this from acquisition/disposition-related tools.

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

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

It gives clear context for when to create a contact and which fields to provide for each type. However, it does not explicitly contrast with update_contact, merge_contacts, or the various attach_*_contact tools, and it never states when not to use it.

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

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

Annotations only provide destructiveHint=false, so the description carries most of the behavioral burden. It discloses that the operation is a write that executes directly, has no ATF effect until committed, and requires no dry-run. This is meaningful behavioral context beyond the annotation, though it does not describe return values or failure modes.

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-load the key concept, state the critical requirement, explain the operational behavior, and close with the workflow. Every sentence earns its place, and the structure makes the tool easy to grasp quickly.

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

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

Given a 14-parameter nested input schema and no output schema, the description supplies necessary workflow and contact guidance but omits several contextual details: whether items can be passed in this call or must be added through add_acquisition_items, what the response contains, and what validation or error behavior to expect. This is a complex tool, and the description is somewhat sparse relative to its shape.

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 57%, and the description adds the important semantic that a supplier contact is required via contactId, contactExternalId, or inline contact. However, it does not clarify the relationship between the top-level items array and the instruction to use add_acquisition_items, nor does it fill in the meaning of the many undocumented parameters.

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

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

The description specifies a precise verb and resource: 'Create a PENDING (uncommitted) acquisition draft.' It also distinguishes this from the commit step by explicitly noting the draft has no ATF effect until committed, making it clear this is a distinct operation from commit_acquisition.

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 an explicit workflow: add items with add_acquisition_items, then finalise with commit_acquisition. It also warns that a supplier contact is REQUIRED and names the three acceptable forms. It does not explicitly contrast this with the sibling acquire tool, but the pending/committed distinction supplies the key usage 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?

Beyond the destructiveHint=false annotation, the description discloses a key behavioral trait: the disposition has no ATF effect until committed and executes directly. The trailing 'Write.' also signals that this is a mutating operation. It does not mention return behavior or error conditions, but the most important safety-relevant behavior is covered.

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

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

The description is short and front-loaded with the core purpose. The final one-word sentence 'Write.' is terse and somewhat cryptic, but the overall structure is efficient and easy to scan.

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

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

Given the tool has 17 parameters, nested objects, no output schema, and a large sibling set, the description is not complete enough. It omits required parameter details, return value information, and account selection guidance. Additionally, the schema allows an 'items' array directly, but the description instructs using add_disposition_items instead, creating ambiguity.

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

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

With only 29% schema description coverage and 17 parameters, the description needed to compensate by explaining key parameters, but it does not. It only mentions sibling tools for adding/committing items, not the meaning of date, requestType, contact, account, or other parameters. The schema alone leaves many parameters effectively undocumented.

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

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

The description clearly states the tool creates a PENDING (uncommitted) disposition draft, using a specific verb and resource. It distinguishes itself by explicitly noting there is no ATF effect until committed, which separates it from commit_disposition and other disposition tools. This is unambiguous and actionable.

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

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

The description provides clear workflow context: create the pending draft, then add items via add_disposition_items, then finalise with commit_disposition. It does not explicitly list alternatives or exclusions, but the sequence guidance makes the intended usage obvious among the many sibling disposition 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?

Beyond the destructiveHint annotation, the description discloses the crucial dry-run-by-default behavior and that confirm:true is required to actually delete. This materially reduces the risk of an agent accidentally executing the destructive action.

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-load the purpose and the safety-critical execution mode. No filler or redundancy; 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 4-parameter tool with complete schema coverage and a destructiveHint annotation, the description plus schema covers the core call correctly. It is slightly incomplete on side effects (e.g., whether deleting a draft also removes its line items) and on what the dry-run preview returns, but these are not blockers to safe invocation.

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

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

Schema description coverage is 100%, so the schema carries the full meaning of id, account, confirm, and auditUser. The description only restates confirm behavior ('pass confirm:true') already present in the schema, adding no new parameter semantics.

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

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

States a specific action ('Delete') and a scoped resource ('PENDING (uncommitted) acquisition draft'), clearly separating drafts from committed acquisitions. However, it does not name or contrast any sibling tools such as delete_acquisition_item or delete_item, so differentiation is implied rather than explicit.

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

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

Gives clear context (only pending/uncommitted drafts) and an explicit invocation instruction ('Dry-run by default; pass confirm:true'). It does not articulate when-not-to-use or name alternatives, so it falls short of being fully prescriptive.

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

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

The description explicitly discloses the destructive nature ('Destructive write') and the safety mechanism: 'Dry-run by default; pass confirm:true.' This goes beyond the annotation by revealing the gated execution model, which is critical for an agent to invoke safely.

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

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

Two short sentences, zero filler. The purpose is front-loaded, followed immediately by the most operationally important caveat (dry-run/confirm). Every word earns its place.

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

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

For a destructive tool, the description adequately conveys scope, safety guard, and execution requirement. It doesn't describe return behavior or failure cases, but the schema handles the dry-run preview detail and no output schema is expected for a delete operation.

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

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

Schema coverage is 100%, so the schema already documents all five parameters, including the confirm behavior. The description repeats the confirm guard but adds no new parameter meaning beyond what the property descriptions already provide.

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 precise verb and resource: 'Remove an item from a pending acquisition.' This clearly distinguishes it from siblings like delete_acquisition (whole acquisition) and delete_item (general item), and the scope is unambiguous.

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

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

The wording 'from a pending acquisition' provides clear context for when to use this tool, implicitly excluding committed acquisitions and whole-acquisition deletion. It does not explicitly name alternative tools or exclusions, so it falls just short of a perfect score.

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 destructiveHint annotation, the description adds the crucial dry-run-by-default behavior and explicitly labels the operation as a destructive write. It does not mention whether deletion is permanent or whether special permissions are required, but the confirmation flow and annotation give agents solid safety context.

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

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

The description is extremely compact: one topic sentence plus a dry-run/confirm note and a destructive-write tag. Every phrase earns its place, and the most decision-relevant information is front-loaded.

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

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

All invocation-critical behavior is covered: target scope, dry-run default, confirmation flag, and destructive nature, with all four parameters documented at 100% schema coverage. It does not describe the return payload or optional account/audit-user nuances, but the schema handles those, and nothing essential to calling the tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description's dry-run and confirm statements largely echo the schema's confirm parameter description without adding new meaning. It does not enrich the account or auditUser parameters beyond what the schema already says.

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 ('Delete') and a precise resource ('PENDING uncommitted disposition draft'), which distinguishes it from committed disposition operations and sibling acquisition/item delete tools. The title and description are aligned and leave no ambiguity about what the tool acts on.

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

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

The description implies when to use the tool—only for pending dispositions—and gives invocation guidance (dry-run by default, pass confirm:true). However, it never explicitly names when not to use it or calls out an alternative sibling tool, so the agent must infer the boundary from the word 'pending'.

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 destructiveHint=true, the description adds critical operational behavior: dry-run by default, confirm:true required to execute, and the immutable audit entry formed by deleteType and deleteNote. This tells the agent exactly what will happen, including the safety mechanism.

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

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

Three short, front-loaded sentences. The core action is stated first, followed by legal constraints, required inputs, and the dry-run safety behavior. No filler or repetition of schema details.

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

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

For a destructive 6-parameter tool with no output schema, the description covers eligibility, required parameters, the dry-run safeguard, and the confirm switch. An agent has everything needed to invoke it safely and correctly.

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

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

Schema coverage is 100%, so the schema already documents all six parameters. The description adds value by clarifying that deleteType and deleteNote form an immutable audit trail and that confirm gates execution from dry-run to actual deletion.

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 and resource, 'Delete a firearm record,' and immediately differentiates this from sibling deletion tools like delete_disposition and delete_acquisition. The ATF 'Duplicate or Error' constraint further pins down exactly which records are eligible.

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

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

It clearly states when deletion is permitted ('only for a Duplicate or Error') and explains the dry-run/confirm workflow. It does not explicitly name an alternative tool for corrections or other cases, but the eligibility constraint strongly implies 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 only provide destructiveHint=false, so the description carries the behavioral burden. It clearly discloses that this commits a regulated record, that confirm:true is required to execute (otherwise a dry-run), and that FastBound may auto-create the receiving FFL's acquisition, reported via headers. The final 'Write.' reinforces the mutating nature without contradicting destructiveHint.

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 pack in purpose, prerequisite, FFL-specific behavior, and commit semantics with almost no fluff. 'Write.' is slightly redundant with 'Commits a regulated record', but it is not harmful and keeps the mutation warning prominent.

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

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

For a complex write tool with 18 parameters, nested contact objects, and no output schema, the description covers the essential behavioral contract: one-step create+commit, dry-run default, FFL auto-acquisition side effect. It could add a bit more about response shape or when to split into pending/commit workflows, but the schema covers the remaining parameter details.

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

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

With only 61% schema coverage, the description compensates by explaining the critical parameters: items.id as inventory GUIDs, requestType=Regular and otherTransfereeEmails for FFL transfers, and confirm:true to turn the dry run into a real commit. It does not cover all 18 parameters, but it targets the ones most essential to correct invocation.

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

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

Description says 'Record a disposition and commit it in one step', naming a specific verb, resource, and the create+commit combination that differentiates it from sibling tools like create_pending_disposition and commit_disposition. It also gives concrete examples (sale, FFL transfer) that clarify scope.

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: immediate one-step disposition, items must already exist in inventory by GUID, and FFL transfers require requestType=Regular plus otherTransfereeEmails. It does not explicitly state when not to use it or name alternatives, so it stops short of a 5.

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

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

The description adds valuable behavioral context beyond annotations: dry-run by default, confirm required to execute, and the explicit 'Write' flag. This is important for an agent to understand side effects. Annotations destructureHint=false do not contradict the description.

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

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

The description is short and front-loaded, with the core action stated first. The trailing 'Write.' is borderline redundant but not harmful. Overall it is 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?

With 11 parameters, no output schema, and a large sibling group, this description is too sparse. It does not describe return values, the dry-run preview shape, or how this tool relates to pending/committed dispositions. An agent would need to inspect schemas or make assumptions to call it correctly.

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

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

Schema description coverage is only 45%, and the description does not compensate enough. It mentions 'destruction date, description, and witnesses' but omits the required 'items' parameter, and does not clarify the relationship between the required 'date' and optional 'destroyed_Date'. Several parameters like account, auditUser, externalId, and price receive no description-level 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 action ('Record and commit a destroyed disposition') and identifies the resource ('inventory items'). The destroyed disposition type is clear from the tool name and description, but it does not explicitly distinguish itself from sibling tools like dispose, dispose_nfa, or dispose_theft_loss.

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 operational guidance ('Dry-run by default; pass confirm:true') but gives no guidance on when to choose this tool over alternatives such as create_pending_disposition, commit_disposition, or dispose. No exclusion criteria or alternative routing is mentioned.

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 single destructiveHint=false annotation, the description usefully discloses that the tool is dry-run by default, that confirm:true is the commit gate, and that it performs a write. This is valuable safety-relevant behavior, though it does not describe what happens after commit or the preview return format.

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 appropriately short and front-loaded: it states the core action first, then the critical dry-run/confirm behavior, then the write nature. There is no filler or redundant detail.

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

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

Given the high parameter count, nested contact object, and lack of an output schema, the description provides only the most essential safety context. It covers dry-run behavior and NFA scope, but does not explain preview output, disposition type sourcing, contact selection, or how to choose among disposition-related siblings. It is minimally viable but not complete.

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

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

Schema description coverage is only about 44%, and many parameters like otsn, ttsn, note, invoiceNumber, and generateTTSN have no descriptions. The description only adds meaning around the confirm parameter, which the schema already covers, so it does not compensate for the low-coverage parameters.

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

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

The description clearly identifies the action ('Record and commit'), the resource ('an NFA disposition'), and the scope ('inventory items'). It does not explicitly contrast with sibling tools like dispose or dispose_destroyed, but the NFA qualifier makes the tool's domain reasonably clear.

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

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

The description implies this is for NFA dispositions and gives the operational key detail that confirm:true is required to actually execute. However, it does not explicitly say when to choose this over the many disposition-related siblings, nor does it state when-not-to-use it.

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

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

Annotations are minimal (destructiveHint: false), so the description carries the burden of behavioral disclosure. It explicitly warns that this tool 'Write's, and it explains the dry-run-by-default behavior with confirm:true required to execute. This adds important behavioral context that the schema alone does not provide, though it stops short of describing post-commit consequences.

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 four terse sentences with the purpose front-loaded, followed by key usage and side-effect information. Every sentence earns its place, including the one-word 'Write.' warning, and there is 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?

For an 11-parameter mutation tool with no output schema, this description covers the core call flow: dry-run, confirm, required inputs, and the write side effect. It does not explain what the dry-run preview returns or explicitly contrast with dispose/dispose_destroyed, but the rich schema and sibling names fill most remaining gaps.

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

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

Schema coverage is 64%, and the description does compensate for some undocumented parameters by grouping 'discovery date and incident numbers' and by clarifying confirm's role. However, it stays silent on note and externalId, and its instruction to 'Provide discovery date and incident numbers' could mislead an agent into thinking those are required when the schema lists them as optional.

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 pair: 'Record and commit a theft/loss disposition for inventory items.' This clearly states the operation and distinguishes it from siblings like dispose_destroyed and dispose_nfa. The title reinforces the same distinction without ambiguity.

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 tells the caller what to provide ('discovery date and incident numbers') and the crucial execution mode ('Dry-run by default; pass confirm:true'). It does not explicitly name alternative tools or when-not-to-use conditions, but the theft/loss scoping and sibling tool names provide clear 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 declare readOnlyHint=true, and the description reinforces this with 'Read'. It also adds valuable behavioral detail by stating the response is the file base64-encoded, which is not implied by the schema or annotations.

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

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

The description is one efficient sentence that front-loads the action, resource, and return format. Every word earns its place, and the final 'Read' reinforces the safety profile without adding bulk.

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 download tool with no output schema, the description adequately covers required input, the completed-PDF precondition, and the base64 return format. Missing details like error behavior or file metadata are minor given the tool's low complexity and full schema coverage.

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 fully documents both form4473Id and account. The description adds no new semantic detail beyond the schema, which is acceptable under the baseline for high coverage.

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

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

The description states a specific action, 'Download', a precise resource, 'completed ATF Form 4473 PDF', and the lookup key, 'by its id'. This clearly distinguishes it from sibling download tools like download_attachment and download_bound_book.

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 makes it clear this is for downloading completed 4473 PDFs, which implies when it should be selected over other download tools. It does not explicitly name alternatives or exclusions, but the resource scope is specific enough for an agent to route correctly.

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 and openWorldHint, so the read-only safety profile is covered. The description adds the otherwise-missing output behavior (base64 encoding), which is valuable given there is no output schema.

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

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

Three terse sentences, front-loaded with the core behavior, and no filler. 'Read.' is short and reinforces the safety profile without wasting space.

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

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

The tool is simple, the schema fully covers parameters, and annotations cover safety. The missing output schema makes the base64 return note important; the only small gap is the lack of any mention of error/failure behavior, which is not essential for basic use.

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

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

The description adds no parameter meaning beyond 'by its id,' while the schema already documents both attachmentId and account at 100% coverage. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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 operation ('Download an attachment file by its id') and clearly identifies the resource. It is easily distinguished from report-download siblings like download_bound_book and download_4473 by resource type.

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 no explicit when-to-use guidance, prerequisites, or alternatives. 'Read.' hints at safe invocation but does not explain when to choose this tool over other download tools or how to obtain an attachmentId.

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 and openWorldHint; the description adds useful behavior beyond that: the auditUser must be recorded by FastBound, output is base64-encoded, and large exports are summarised. It does not specify the summarisation threshold, but it still provides meaningful transparency.

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

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

Three short sentences front-load the core purpose, then give prerequisites and return behavior. Every clause is informative and there is no redundant filler.

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

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

For a two-parameter, no-output-schema tool, the description adequately covers purpose, prerequisites, output encoding, and an important caveat. It could still clarify what 'summarised' means and what threshold triggers it, so it is not fully complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add much beyond the schema for either parameter, though it does reinforce that auditUser is tied to FastBound's audit trail.

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 the exact resource ('A&D bound book export') and action ('Generate and download'), clearly separating it from sibling download tools like download_4473, download_attachment, and download_multiple_sale_report. It is specific and 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 states the prerequisite auditUser email and the output mode, giving an agent enough context to know when this tool is appropriate. It does not explicitly contrast it with alternatives, but the resource is unique enough that no exclusion is needed.

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

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

Annotations already declare readOnlyHint=true, and the description adds the important behavioral detail that the file is returned base64-encoded. The closing 'Read.' reinforces the read-only nature. There is no contradiction with annotations.

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

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

Two short sentences with no filler. The resource and action are front-loaded, and the return-format detail 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 read-only download with full schema coverage and no output schema, the description gives the essential return format and target resource. It omits error behavior, but that is a minor gap given the low complexity and helpful annotations.

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

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

Schema description coverage is 100%, so all three parameters are already fully documented. The description mentions the two IDs but adds no semantics beyond what the schema provides, which is at baseline.

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

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

The description names the exact resource (Multiple Sale report attachment), identifies the ATF form types, and notes the two required identifiers. This clearly distinguishes it from generic download_attachment and other download 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?

It states how to call the tool ('by report id and attachment id') but gives no guidance on when to use it instead of siblings such as download_attachment or download_4473. No alternatives or exclusions are mentioned.

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 idempotentHint=true and destructiveHint=false. The description adds that the operation is a 'Write' and 'Executes directly,' which conveys immediate mutation. It does not elaborate on side effects, audit implications, or account selection, but it does not contradict the annotations.

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

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

The description is very short and front-loads the core action. 'Executes directly' adds useful behavior, though the trailing 'Write.' is arguably redundant with both that phrase and the annotations. Overall, it is compact with no significant 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 supplies the key condition ('pending disposition') and execution behavior ('Executes directly'), while schema and annotations cover parameters, idempotency, and non-destructiveness. It leaves side effects unspecified and there is no output schema, but for a simple price-setting operation the provided information is sufficient for correct use.

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

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

All parameters are fully described in the input schema (100% coverage), so the schema carries the parameter documentation burden. The description adds little beyond restating that the sale price is being set, which matches the baseline expectation for full schema coverage.

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

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

The description clearly states the operation: 'Set the sale price of an item on a pending disposition.' It identifies the verb, resource, and lifecycle constraint. It does not explicitly name or contrast with sibling tools, but the scope is specific enough that an agent can understand the tool's primary function.

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 useful context by restricting the action to a 'pending disposition' and noting that it 'Executes directly.' However, it does not say when to avoid this tool or mention alternatives such as update_disposition, update_item, or add_disposition_items, so usage guidance is only implied.

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

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

The annotations already declare readOnlyHint and openWorldHint, and the description confirms 'Read-only,' so there is no contradiction. The description adds the specific property list and the connectivity-check use case, but it does not disclose deeper behavioral traits such as output structure, pagination, or failure modes. Given the annotations cover the safety profile, this is acceptable but not exceptional.

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

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

The description is two short sentences, front-loads the operation and resource, and is generally economical. The final 'Read-only.' is somewhat redundant with the readOnlyHint annotation, but it is short and harmless.

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 read-only operation with one optional, fully documented parameter and no required parameters, the description is adequate. It lists the kind of data returned (number, name, items in inventory, owner), which partially compensates for the lack of an output schema. No auth or error details are necessary for a low-risk read operation.

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

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

The single optional parameter 'account' is fully described in the input schema with aliases, the list_accounts reference, and the default behavior of using the active account. Schema coverage is 100%, so the tool description does not need to restate this; it adds no additional parameter meaning beyond the schema.

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

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

The description uses a specific verb ('Read') and names the resource ('FastBound account properties and settings'), with concrete examples like number, name, items in inventory, and owner. It does not explicitly differentiate from siblings such as list_accounts or use_account, but the get-vs-list distinction is reasonably clear.

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

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

The description says it is 'useful as a connectivity/credential check,' which gives a clear use case. However, it does not explicitly say when to prefer this over list_accounts or use_account, nor does it state when not to use it. The schema parameter references list_accounts, but the description itself provides no exclusion or 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?

The annotations already provide readOnlyHint and openWorldHint, and the description's 'Read-only' reinforces this but does not add new behavioral detail. It does not explain not-found behavior, response shape, or side effects, but for a simple read operation the annotations carry most of the burden without 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?

Two short sentences with no filler. The core purpose and identifier scope are front-loaded, and the read-only note is a single word. Every part 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?

Given the low complexity, complete parameter documentation, and read-only annotations, the description is largely sufficient for an agent to call the tool correctly. It does not describe the response object, but the name and verb make the expected return reasonably clear, and no output schema exists to clarify further.

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 fully documents id, idType, and account. The description's mention of 'FastBound GUID id or your externalId' aligns with the idType enum, but it does not add meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Retrieve'), a clear resource ('a single acquisition'), and identifies the two supported identifier types ('FastBound GUID id or your externalId'). This clearly distinguishes it from search-focused siblings like search_acquisitions or item-specific tools like get_acquisition_item.

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 tool is clearly positioned for fetching one acquisition by exact identifier, which implies it is not for searching or listing. It does not explicitly name alternatives or say when not to use it, but the single-record scope and identifier semantics provide adequate usage 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?

The description adds no behavioral context beyond what the annotations already declare: readOnlyHint=true and openWorldHint=true. The phrase 'Read-only' duplicates the annotation rather than disclosing additional behaviors such as not-found handling, output shape, or whether the account parameter changes scoping.

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 extremely compact and front-loads the core purpose in the first sentence. The second sentence, 'Read-only,' is redundant with the readOnlyHint annotation but is brief and harmless; overall the structure wastes no 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 the low complexity, complete parameter documentation, and safety annotations, the description is largely sufficient for an agent to invoke the tool correctly. A small gap is the lack of any statement about return contents when no output schema exists, but 'Retrieve' reasonably implies it returns the item.

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

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

The input schema provides complete descriptions for all three parameters, including the distinction between the acquisition GUID and the acquisition item GUID, and the account override behavior. The description adds no parameter-level meaning, so it rests at the baseline for full schema coverage.

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

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

The description states a specific verb ('Retrieve'), a precise resource ('a single item within an acquisition'), and a scope boundary that distinguishes it from sibling tools like get_acquisition, search_acquisitions, and get_item. It clearly communicates this is a targeted read of one acquisition item rather than a list or an unrelated item lookup.

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 explicit guidance on when to choose this tool over alternatives, such as get_item, search_items, or get_acquisition. It does not mention exclusions, prerequisites, or related tools, so the agent must infer usage solely from the name and resource phrasing.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, and the description's 'Read-only' merely echoes the readOnly annotation without contradicting it. It adds no new behavioral detail such as error conditions, authentication needs, or return format, but the safety profile is already covered by annotations.

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

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

The description is a single front-loaded sentence that states the resource, identifier options, and read-only nature with zero filler. Every word contributes meaning.

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

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

For a simple read-only lookup tool, the description plus fully documented schema and safety annotations are largely sufficient. The only notable missing element is explicit guidance on when this tool should be chosen over search_contacts, and there is no output schema that would need return-value explanations.

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 fully documents all three parameters. The description only restates the idType distinction already present in the schema and adds no examples, default clarifications, or format details beyond it.

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

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

The description uses a specific verb ('Retrieve') and names both the resource ('a single contact') and the two lookup keys ('FastBound GUID id or your externalId'). This clearly distinguishes it from search_contacts, which returns multiple contacts, and update_contact, which modifies.

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

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

It implies the tool is for retrieving exactly one contact when you already have an identifier, but it never explicitly says when to use it instead of search_contacts or lists alternatives. The 'Read-only' tag gives safety context, but there is no direct routing guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description merely repeats 'Read-only' without adding context beyond that. The description does not disclose what happens on not-found or whether the response includes related items, but given the annotations carry the safety profile, a baseline 3 is appropriate.

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 sentence with zero waste. The purpose and key id-type distinction are front-loaded, and every word carries meaning.

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

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

For a straightforward get-by-id operation with annotations covering read-only and open-world behavior, the description is adequately complete. It does not describe the return payload, but no output schema exists and the tool's simplicity reduces the need. A minor gap is the lack of any note about the `account` parameter, though the schema covers it.

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

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

Schema descriptions cover 100% of the three parameters, including the idType enum semantics. The description only echoes the id type distinction and adds no syntax or format details beyond what the schema already provides. With high schema coverage, 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?

The description clearly states a specific verb ('Retrieve') and a precise resource ('a single disposition'), and explicitly names the two identifier types (FastBound GUID id or externalId). This distinguishes it from sibling tools like search_dispositions, which retrieve multiple records, and from get_acquisition, which targets a different resource.

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

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

The description provides clear context for when to use the tool: when you have a specific disposition identifier. It even clarifies the two id types via the parameter mention. However, it does not explicitly mention alternatives or exclusions (e.g., 'use search_dispositions for filtering'), so it stops short of full 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?

The annotations already provide readOnlyHint=true, and the description reinforces this with 'Read-only.' It adds useful context about the single-record scope and identifier types, though it doesn't describe not-found behavior or any external-world caveat hinted by openWorldHint=true.

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?

One tight sentence names the action, the object, the key fields, and the read-only nature. Every word earns its place and the most important scoping information is front-loaded.

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

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

For a single-record lookup with one required parameter and clear annotations, the description is largely sufficient. It doesn't explain the return shape or error handling, but the output schema is absent and the stated purpose is enough for a competent agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline applies. The description adds a little meaning by explicitly mentioning FastBound GUID and externalId, which maps to the id/idType relationship, but it doesn't significantly extend what the schema already documents.

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

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

The description uses a specific verb ('Retrieve'), names the resource ('a single firearm record'), and identifies the two lookup keys (FastBound GUID or externalId). This clearly distinguishes it from search/listing siblings like search_items and from acquisition/disposition record tools.

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

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

The description makes the direct-lookup use case clear: retrieve one specific item by a known identifier. It doesn't explicitly call out search_items as the alternative for queries/filters, but the context strongly implies that this is the point lookup 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?

The description only restates 'Read-only', which is already captured by readOnlyHint=true, and does not explain the openWorldHint annotation or any other behavioral traits such as default pagination, account selection, or result scope. It adds little beyond the annotations.

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

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

The description is extremely concise: two short sentences with no redundant wording. The core purpose is front-loaded and every word contributes.

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 listing tool with three optional and fully documented parameters, the description is minimally adequate. However, it does not mention what the response contains, default pagination behavior, or how this relates to search_dispositions, so it is not fully complete.

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

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

Schema description coverage is 100%, so all three parameters are already well documented. The description adds no additional parameter context, but none is needed because the schema fully explains skip, take, and account.

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

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

The description uses a specific verb ('List') and a precise resource ('dispositions that have an associated ATF Form 4473'), which clearly distinguishes it from related tools like search_dispositions or get_disposition. The filter is explicit and unambiguous.

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

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

No guidance is given about when to use this tool versus alternatives such as search_dispositions or list_disposition_items. The description implies a use case but provides no exclusions, prerequisites, or comparison to sibling 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?

The description adds valuable behavioral context beyond the readOnlyHint annotation by stating 'Server-local: makes no API call.' It also discloses that the tool reveals whether writes are enabled and which account is active, which helps the agent reason about multi-account state without invoking the tool.

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

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

The description is compact, front-loaded with the core action and result fields, and every sentence contributes distinct information: returned fields, how account targeting works, and the local no-API-call behavior. There is 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?

For a zero-parameter, read-only, server-local listing tool, the description is complete. It names the returned fields, explains how the account parameter works across other tools, and clarifies the relationship to use_account. No output schema is present, but the description already enumerates the observable result contents.

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

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

There are zero parameters and the schema coverage is effectively complete, so the description does not need to compensate for undocumented inputs. The baseline of 4 applies because there is no parameter surface to clarify.

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

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

The description uses a specific verb and resource: 'List every FastBound account this server is configured for', and then enumerates exactly which fields are returned. This clearly distinguishes it from siblings like get_account and use_account by covering the full set of configured accounts rather than a single account or an account-switching action.

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 clear contextual guidance: pass an alias or account number as `account` on any tool to target it, or use use_account to change the active account. It implies the tool's role in discovering available accounts and their aliases, but it does not explicitly say when to choose this over get_account or list excluded 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?

The description's only behavioral statement, 'Read-only,' duplicates the readOnlyHint annotation and adds no additional behavioral context. It does not explain openWorldHint, pagination, response shape, or any other runtime behavior, leaving the agent to infer behavior from the name and schema.

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

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

The description is very short and front-loaded with the operation. The second sentence, 'Read-only,' is somewhat redundant with the readOnlyHint annotation, but the structure is clean and free of 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 simple read-only list with one required parameter, the description is minimally sufficient. However, with no output schema, the absence of return-format or pagination information and the lack of guidance on alternatives leave moderate gaps for an agent.

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

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

Schema description coverage is 100%, so the input schema already documents id as the disposition GUID and account as an optional account selector. The description adds no parameter meaning beyond that, matching the baseline 3 for full schema coverage.

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

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

The description names a specific verb and resource: 'List the items on a disposition.' This is clearly distinct from sibling tools like get_disposition or add_disposition_items, though it does not explicitly contrast itself with them.

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

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

No guidance is given on when to use this tool over alternatives such as get_disposition, search_dispositions, or list_4473_dispositions. The phrase 'List the items on a disposition' states the operation but provides no exclusions, prerequisites, or selection conditions.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true. The description adds that the operation returns allowed values/reference lists rather than records, which is useful context. However, it does not describe output format, account-dependent variation, or any other behavioral nuances beyond what the annotations convey. This is adequate but not 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?

Three sentences, each earning its place: what the tool returns, when to use it, and its safety profile. The most important information is front-loaded, and there is no fluff or redundancy that weakens the 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 list tool with two parameters and one required enum, the description is nearly complete: it identifies the resource, the allowed inputs are in the schema, and the return concept (allowed values) is stated. The absence of an output schema makes a slightly more explicit return-format note desirable, but overall nothing critical is missing for correct invocation.

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

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

The input schema provides 100% coverage with clear descriptions for both 'list' (enum plus examples) and 'account' (alias/account number with fallback to active account). The description only repeats examples from the schema and adds no new parameter-level semantics, so it sits at the baseline.

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

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

The description opens with a specific verb and resource: 'Return one of FastBound's reference lists (allowed values).' It then names concrete examples (caliber, manufacturer, type, condition, location, importer) that clearly distinguish this from sibling tools like list_accounts or search_items. The tool's purpose is unambiguous.

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

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

It explicitly states when to use the tool: 'before creating or editing records' to discover valid values. It does not explicitly name sibling alternatives or state when not to use it, but the use case is clear enough that an agent can route correctly. The 'Read-only' note reinforces safe usage.

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

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

The readOnlyHint/openWorldHint annotations already cover safety; the description adds account scoping and the write-header use case, but does not reveal behavior such as return shape or pagination. There is no contradiction with 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 sentences with front-loaded purpose and a clear use case. The final 'Read-only.' is redundant given readOnlyHint=true, so it is not perfectly earned, but the overall description is compact and scannable.

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

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

For a simple read-only list with one optional parameter, the description is largely complete: it identifies the resource, the account scope, and why an agent would call it. It does not describe the output shape, but absent an output schema this is a minor gap rather than 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?

The only parameter, 'account', has 100% schema description coverage. The main description adds no additional parameter semantics, so the baseline of 3 applies.

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

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

The description uses a specific verb and resource ('List users on the account') and states the practical purpose (finding valid emails for the X-AuditUser header), so an agent can distinguish it from the many account/contact/search 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?

It gives explicit guidance for when to use the tool: 'Use this to find valid emails for the X-AuditUser header required on write operations.' It does not state when-not-to-use or name alternatives, but none of the siblings is a competing user-list tool, so this is clear enough.

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 clearly discloses that the operation is a write and that it is dry-run by default unless confirm:true is passed. This is essential behavioral information for an agent to avoid unintended side effects. It does not cover edge cases like re-locking or locked-state errors, but it adds meaningful value beyond the annotations.

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

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

The description is extremely concise: three short clauses, each earning its place. The primary action is front-loaded, the dry-run caveat is immediately given, and the 'Write' note clarifies the mutation behavior without wasting 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 the annotations, complete parameter documentation, and no output schema, the description is largely sufficient for invocation. It explains the key operational nuance (dry-run by default) and the write nature of the call. It could add detail about return values or what happens after a disposition is locked, but nothing essential to calling the tool 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 four parameters are already documented in the schema. The description only restates the confirm parameter's role ('pass confirm:true'), adding little semantic value beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description names a specific verb ('Lock'), a specific resource ('disposition'), and the intended effect ('prevent further edits'). It is clearly distinct from sibling tools like delete_disposition or commit_disposition, so an agent can immediately tell what this tool is for.

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 clear context for when to use the tool: to lock a disposition against further edits. It also explains the critical dry-run vs. confirm execution mode. However, it does not explicitly name alternatives or state when not to use this tool, such as when the goal is merely to commit rather than lock.

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

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

The description says 'delete a license' and labels itself 'Write,' which implies a destructive/mutating operation, while annotations declare destructiveHint=false. Per the rubric, contradicting the annotation forces a score of 1. The additional 'Executes directly' context is useful, but the contradiction is the dominant signal.

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 pack purpose, action-specific parameter guidance, and execution behavior with no filler. The most important content is front-loaded.

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

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

For a 9-parameter mutation tool with no output schema, the description captures the core action logic and immediate execution, but it omits what the call returns or how success/failure is signaled. The schema covers most parameters, yet the agent is left to guess the response shape and any side effects beyond 'Write.'

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 78%, and the description adds an actionable cross-parameter rule: type+number for add, licenseId for update/delete. This goes beyond the individual schema property descriptions by tying the action enum to specific parameter requirements.

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 the exact resource ('a license on a contact') and the full set of verbs ('Add, update, or delete'), so an agent immediately knows what the tool does. It also differentiates itself from the contact/item/acquisition/disposition siblings by focusing specifically on license management.

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 conditional guidance: 'For add provide type+number; for update/delete provide licenseId.' This tells the agent which parameters to supply for each action. It does not name alternatives or exclusions, but no sibling tool directly competes with this license-management scope.

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 only openWorldHint in annotations, the description carries the behavioral burden. It usefully classifies which actions are writes and the permission requirement, but it does not disclose side effects, idempotency, whether delete is destructive, or how updates behave. This is adequate but not 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 tight sentences front-load the full action set, immediately mark read vs write, and highlight the create parameter requirements. No filler or repetition of schema details.

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 multi-action tool with seven parameters and no output schema, the description covers action semantics, permissions, and create requirements. It could add more about update/delete semantics or side effects, but the core information needed to select and invoke the tool is present.

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

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

Schema coverage is 71%, and the schema already documents most parameters. The description adds value by saying create needs name, url, and events, but it does not explain the description parameter or further disambiguate action-specific requirements beyond what the schema states.

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

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

The description names the resource (webhooks) with concrete verbs: list event types, get, create, update, delete. It also distinguishes read actions from write actions, so an agent can immediately understand the tool's scope even without opening the schema.

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

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

It gives clear action-level guidance: reads are list_events/get, writes are create/update/delete, and writes require FASTBOUND_ALLOW_WRITES. It also states the required parameters for create. It does not mention alternatives because there are no webhook-specific siblings, so no when-not-to-use guidance is needed.

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

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

The description discloses the destructive nature ('Destructive write'), the exact behavioral consequence ('references move to the winner'), and the dry-run default. This adds meaningful context beyond the destructiveHint annotation.

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 deliver the essential meaning without wasted words. The key information—what merges, what happens to references, and how to confirm—is front-loaded.

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

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

For a 5-parameter tool with no output schema, the description covers the core behavior, safety profile, and invocation guard. The account and auditUser parameters are fully documented in the schema, so nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds semantic value by explaining the relationship between winningContactId and losingContactId ('keep... discard... references move to the winner'). This clarifies what the merge actually does beyond the schema field names.

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

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

States a specific verb and resource: 'Merge two duplicate contacts,' and immediately defines the outcome: keep winningContactId, discard losingContactId. This clearly differentiates it from sibling tools like update_contact or create_contact.

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 identifies the use case ('duplicate contacts') and provides the critical confirmation gate ('Dry-run by default; pass confirm:true'). It does not explicitly list alternatives or exclusions, but the purpose is specific enough that an agent can select it correctly.

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

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

The description discloses key behavioral context beyond the destructiveHint annotation: it is a dry-run by default, and execution requires confirm:true. It also labels the operation as 'Write,' reinforcing the mutation. This gives an agent a clear safety-relevant expectation without contradicting the annotations.

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

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

The description is two short sentences with no filler. The core action and the critical dry-run/confirm behavior are front-loaded, and the final 'Write.' is an efficient signal of mutability.

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, combined with 100% schema coverage and the destructiveHint annotation, covers the essential aspects: target, key, pending state, and confirmation requirement. It does not describe the dry-run response shape, but for a simple destructive tool with a schema this concise, that is a minor omission rather than a blocking 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?

The input schema already provides 100% description coverage for all five parameters, so the baseline applies. The description mentions the inventory item GUID and confirm:true, but these merely echo the schema rather than adding deeper semantics 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 names a specific verb ('Remove'), a specific resource ('item from a pending disposition'), and the identifying key ('inventory item GUID'). This clearly differentiates it from siblings like add_disposition_items, delete_disposition, and undispose_item.

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 states that the operation targets a pending disposition and that confirmation is required via confirm:true, which implies when to use it. However, it does not explicitly contrast it with alternatives such as undispose_item or list_disposition_items, leaving the usage boundaries to be inferred.

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

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

The description repeats the annotation-provided read-only nature and adds the 'intake events' framing, but it does not disclose additional behavioral traits such as result ordering, pagination defaults, or whether filters combine. The readOnlyHint and openWorldHint annotations already cover the safety profile, so the lack of contradiction keeps this at a mid 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?

Two sentences front-load the resource and action, then compactly list filter categories. 'Read-only' is redundant with the annotation but not verbose enough to hurt; the entire description is appropriately sized.

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

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

For a 14-parameter search tool with no output schema, the description is thin: it does not state whether filters combine with AND/OR, what the response contains, or how pagination behaves beyond the schema's skip/take descriptions. It is sufficient to choose the tool but not fully self-contained for correct invocation.

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

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

Schema description coverage is only 21%, so the description must compensate; it does group many parameters into useful categories (PO/invoice/tracking, supplier contact, item, manufacturing). However, it omits some parameters such as id, externalId, and account, and it does not map the categories to exact parameter names, leaving gaps in guidance.

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

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

The description opens with a specific verb and resource: 'Search acquisition records (intake events)' and enumerates the filter dimensions (type, PO/invoice/tracking number, supplier contact, item, manufacturing flag). This separates it from sibling search tools such as search_items and search_dispositions by naming the acquisition/intake domain.

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 filter list implies the tool is appropriate when looking up acquisitions by purchase-order, invoice, tracking, supplier-contact, or item criteria, but it never states when not to use it or points to alternatives. There is no explicit tool-selection guidance such as 'for disposition records, use search_dispositions'.

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

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

The annotations already provide readOnlyHint=true, and the description repeats 'Read-only' without adding much new safety information. It does add the entity scope and filter dimensions, but omits matching semantics, pagination behavior, and the shape of the result set.

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 deliver the essential information without redundancy, putting the action and scope first. The extra filter detail follows naturally and 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 tool with 11 parameters and no output schema, the description is minimally workable but not fully self-contained: it does not describe the return value, pagination behavior, filter combination semantics, or account selection. The read-only annotation helps, but an agent would still need to infer or probe several behaviors.

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

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

With only 27% schema description coverage, the description's filter list is useful for grouping the many undocumented text parameters (name, FFL number, trade name, organization name). However, 'name' is ambiguous about which of firstName/lastName/middleName/suffix it means, and no exact vs partial matching semantics are stated.

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

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

The description uses the specific verb 'Search' with the concrete resource 'contacts', and it delineates the entity types (individuals, organizations, and FFLs). This makes it clearly distinguishable from sibling search tools such as search_items.

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 resource name and the listed filter attributes, but the description does not name alternatives or state when to prefer get_contact over this broad search. It also does not specify whether filters are optional or whether omitting them returns all contacts.

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

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

The description's 'Read-only' statement merely repeats the readOnlyHint annotation, and openWorldHint is not addressed. It adds no behavioral context such as pagination behavior, default result ordering, account scoping consequences, or what happens when no filters are provided, so it contributes little beyond structured metadata.

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

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

Two short sentences with no filler; the action and resource lead, the domain qualifier is compact, and the filter summary plus read-only flag follow. 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 17-parameter search tool with no output schema, the description gives enough context to understand what is being searched and which logical filter groups exist, while skip/take/account/include4473 are covered by schema descriptions. It is slightly incomplete because it does not mention result-shaping flags like include4473 or special disposition subtypes, but it is adequate for safe invocation.

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

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

With schema description coverage at only 24%, the description helps by grouping filters into meaningful categories ('TTSN/OTSN, PO/invoice/tracking, recipient contact, item'), which maps to many parameters. However, it omits semantically important parameters like isManufacturingDisposition and externalId, so it only partially compensates for the schema's low coverage.

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

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

States a specific verb and resource: 'Search disposition records', and defines the domain with the parenthetical 'firearms leaving inventory: sales, FFL transfers, theft/loss, destroyed'. This clearly separates it from search_acquisitions and other record-type search tools, even without naming a 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 description implies a broad search use case and lists filter categories, but it never states when to prefer this tool over alternatives such as get_disposition, list_disposition_items, or list_4473_dispositions. There are no explicit exclusions or when-not-to-use conditions, leaving the routing decision to inference.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with 'Read-only.' It adds useful behavioral detail beyond annotations by stating that the tool returns 'a page of items plus the total record count,' giving the agent a clear sense of pagination and response shape. It does not mention sorting or defaults, but the read-only annotation lowers the burden.

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 earn their place: purpose, filter capabilities, return shape, and read-only safety. The most important information is front-loaded, and there is no repetition or filler.

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

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

For a 29-parameter search tool with no output schema, the description says what is searched, that it is read-only, and that it returns a page plus total count. However, it omits filter combination semantics, pagination defaults, account behavior, and what item fields appear in the response. That is a meaningful gap given the tool's complexity and the sparse schema coverage.

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

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

Schema description coverage is only 28%, so the description needed to compensate for many undocumented parameters. It names broad filter categories—serial, manufacturer, model, type, caliber, status, date ranges, TTSN/OTSN, and more—which is helpful high-level guidance. But it does not clarify boolean parameters, ID parameters, filter combination behavior, or the many other fields, so compensation is partial.

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

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

Description clearly states a specific verb and resource: 'Search the firearm inventory (the A&D book).' It enumerates many filter dimensions, distinguishing it from sibling search tools like search_acquisitions, search_dispositions, and search_contacts. The title alone would be generic, but the description resolves the ambiguity.

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 clear context: it is a read-only search over the A&D firearm inventory, so an agent can infer it is for lookup rather than mutation or acquisition/disposition searches. However, it does not explicitly name alternatives or exclusion criteria, so it stops short of the strongest possible 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 idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds 'Executes directly' and 'Write', which provide some behavioral context beyond annotations — indicating immediate execution and mutation. However, it does not explain outcomes such as overwriting existing contacts or response format. With annotations covering safety, this modest additional context earns a 3.

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

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

The description is a single declarative sentence: 'Set the acquisition (source) contact on an item. Executes directly. Write.' It is extremely concise, front-loaded with the core purpose, and contains zero filler. Every word earns its place, and it is adequately structured for quick scanning.

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

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

For a simple mutation tool with 4 parameters (schema-covered), no output schema, and clear scoping via 'on an item', the description is reasonably complete. It does not explicitly address return values, but that is acceptable given the absence of an output schema and the straightforward nature of the operation. It could be slightly more complete by naming the sibling for contrast, but it does not leave critical gaps.

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

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

Schema description coverage is 100%, so all four parameters are documented in the schema. The description adds no new information about parameters beyond what the schema provides. Per the calibration rule, when schema coverage is high, the baseline is 3. The description does not reduce clarity, but it also does not enhance parameter understanding.

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

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

The description states the verb 'Set' and the resource 'acquisition (source) contact on an item', which is clear and specific. However, it does not explicitly differentiate from the sibling tool 'attach_acquisition_contact', even though the phrase 'on an item' implies item-level scope rather than acquisition-level. It's not a tautology and is a distinct operation, so a 4 is appropriate.

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

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

The description provides no guidance on when to use this tool versus alternatives like 'attach_acquisition_contact'. It does not mention prerequisites, context, or exclusions. The only hint is 'on an item' which implies item-level usage, but there is no explicit when-to-use instruction. This falls short of the 3 baseline for 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 already provide idempotentHint=true and destructiveHint=false. The description adds useful behavioral context by saying it links the item to the system's record and guarantees no other fields are modified. It stops short of describing error cases or permissions, but the core behavioral profile is adequately disclosed.

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

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

The description is a single sentence that front-loads the action, scope, and exclusion. Every phrase earns its place, and the final 'Write.' is acceptable, if brief, context.

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

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

For a simple, focused write tool with 100% schema coverage and clear annotations, the description is nearly complete. It lacks an explicit mention of the response value or error behavior, but those are not required for this operation's core use.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds slight extra meaning by explaining that externalId links to 'your system's record,' but it does not substantially enrich the parameter understanding beyond the schema.

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

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

The description uses a specific verb and resource: 'Set or change only the externalId of an item.' It also distinguishes itself from broader tools by explicitly stating it does so 'without touching other fields,' making its unique purpose clear.

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

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

The phrasing 'only the externalId' and 'without touching other fields' gives clear context for when this tool is appropriate versus a broader update tool like update_item. It does not explicitly name the alternative, but the intended narrow use case is 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?

Annotations mark destructiveHint=true, and the description reinforces this with 'Write.' It adds value by disclosing the dry-run default and the confirm gate, which is exactly the kind of behavioral nuance an agent needs before invoking. No contradiction with 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?

Three short sentences carry the essential message: what it does, how to apply it, and that it is a write operation. Front-loaded and free of 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 destructive operation with no output schema, the description covers the critical safety aspect (dry-run by default) and the confirm requirement. It does not describe response shape or side effects beyond returning the item to inventory, but the essential call guidance is present.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including the confirm behavior. The description adds minimal parameter-level meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description states a specific action ('Reverse a disposition') and a precise outcome ('return a disposed firearm to available inventory'), clearly distinguishing this from sibling tools like delete_disposition or dispose. The verb-resource pairing is unambiguous and actionable.

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 clear operational context: dry-run by default and confirm:true to apply. It does not explicitly name when to prefer this over alternatives, but the purpose is specific enough that an agent can infer when it 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?

Beyond the annotations, the description discloses read-merge-write semantics (unspecified fields retain values), a dry-run default with confirm:true required to execute, and that this is a write operation. These are the key behavioral traits needed to invoke it safely.

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 with no filler: action and object first, merge behavior second, dry-run/confirmation third. The final 'Write' is a useful explicit flag rather than 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 highly parameterized tool with no output schema, the description covers target state, merge behavior, and execution control well. It does not describe the return/dry-run preview shape or edge cases like providing no editable fields, but those are minor compared to what is captured.

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?

Description adds domain meaning by grouping fields as header fields and explaining confirm's role, and schema covers confirm/account/auditUser. However, schema coverage is only 45% and several parameters (date, note, invoiceNumber, shipmentTrackingNumber) have no explanation in either the description or 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 action ('Edit header fields' on a PENDING acquisition) and enumerates the affected fields, making it easy to distinguish from update_acquisition_item and commit_acquisition. The read-merge-write note further clarifies what the tool does.

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

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

It clearly scopes the tool to PENDING acquisitions, which tells an agent when this is appropriate and implicitly rules out committed/deleted acquisitions. It does not explicitly name alternative tools or state when-not-to-use it, but the context is strong.

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