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

With no annotations provided, the description carries the full burden and discloses important behavioral traits: writes are gated by business rules, errors are machine-readable with a { code, message } shape, and attempts are audit-logged. It stops short of describing success responses or permission requirements, but adds meaningful safety and error 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?

Two sentences, front-loaded with the core action, and every clause earns its place by adding error behavior and audit context. No fluff or redundancy.

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

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

For a write operation with no annotations and no output schema, the description should compensate by explaining params and success behavior. It covers error handling but leaves essential invocation details undocumented, making the tool only partially self-explanatory.

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 0% and the description does not explain any of the four required parameters (orderId, noteId, text, author). The schema only provides types and minLength, leaving the agent without semantic meaning for any field.

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 'File' and identifies the resource 'triage note against an order', clearly distinguishing it from sibling tools like cancel_order or get_note. The purpose is immediately understandable.

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 versus alternatives such as search_note or read_audit_log. The description implies its use when adding a note to an order but does not state exclusions or prerequisites.

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

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

With no annotations, the description carries the full burden. It discloses the empty-set behavior ('zero metrics for an empty set') and the return structure ('each row has a key, member pks and numeric metrics'), which is useful. However, it doesn't state whether the operation is read-only, doesn't cover grouped empty-set behavior, and is silent on potential side effects. It adds some context but not comprehensive.

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

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

The description is three sentences, front-loaded with the primary purpose. It is efficient, with no filler, though some details (like the sum property) are missing rather than excessive. Structure is logical: action, parameter behavior, return format, and client-side usage.

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 has two parameters and no output schema, so the description must fully explain inputs and outputs. It covers the return structure and empty-set case, but omits critical information: the identity of the numeric property to sum, and edge cases for grouped empty sets. The missing sum parameter makes the tool incomplete for its stated optional functionality, so agents cannot reliably use it as intended.

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 0%, so the description must explain parameters. It explains group_by usage and implies pks are customer identifiers, but it fails to specify which numeric property is summed ('optionally sum a numeric property' with no parameter to select it). This is a critical gap—the agent cannot correctly invoke the sum functionality based on this description. Group_by is clarified, but pks semantics are vague.

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 action ('Count the selected Customer objects') and a resource ('Customer objects'), distinguishing it from search/get operations. It also mentions an optional sum, but doesn't explicitly name sibling aggregation tools (aggregate_order, etc.), so it lacks explicit differentiation. Still, the verb+resource is specific enough.

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

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

The description explains parameter usage ('Omit group_by for one whole-set total... or group by a property') and advises client-side filtering, but it does not state when to choose this tool over alternatives like search_customer or set operations. No exclusions or explicit comparisons to siblings are provided, leaving selection to inference.

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

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

With no annotations provided, the description adds useful behavioral detail beyond the schema: whole-set results use key null, empty sets produce zero metrics, and each row contains a key, member pks, and numeric metrics. It remains slightly vague about which numeric property is summed, but the behavior described is adequate for an aggregate 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 sentences cover the core action, grouping modes, empty-set behavior, and output shape without padding. The sentence 'Returns set and values...' is slightly imprecise, but the overall structure is front-loaded and 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 two-parameter aggregation tool, it covers the input selection, grouping options, empty-set result, row structure, and follow-up workflow using returned pks. Missing details are the exact numeric property being summed and explicit read-only confirmation, but no output schema or annotations are present to fill those 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 0%, so the description must compensate. It maps pks to 'selected Note objects', explains group_by as grouping by a property, and explains omission behavior. It does not enumerate the enum values, but the schema already exposes them via the enum list.

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 ('Count... optionally sum') on a specific resource type ('Note objects'), which clearly distinguishes it from sibling aggregate_* tools for other resources. The grouping and return behavior reinforce that this is an aggregation tool rather than a simple get/search.

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 conditional guidance: omit group_by for a whole-set total or use group_by to break results into rows, and suggests filtering rows client-side. It does not explicitly contrast the tool with sibling note tools, but the within-tool usage context 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?

With no annotations, the description carries the behavioral burden: it explains the null key for whole-set totals, zero metrics on empty sets, and the row shape with key/member pks/metrics. It does not cover auth or rate limits, but aggregation is naturally non-mutating and the edge-case disclosure is strong.

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

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

Every sentence earns its place: the core action comes first, followed by grouping variants, return shape, and a practical follow-up hint. 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 tool with no output schema, the description provides return-row anatomy (key, member pks, numeric metrics) and an empty-set edge case, which is enough to call it correctly. The main gap is the lack of an exact example or field-name mapping, but this is not critical for selection and invocation.

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

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

Schema description coverage is 0%, yet the description compensates by explaining pks as selected Order objects, sum as an optional numeric metric, and group_by as the grouping dimension. It stops short of naming the exact sum value (total) or enumerating valid group_by values, but the enum in the schema covers those details.

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: 'Count the selected Order objects and optionally sum a numeric property.' It clearly identifies aggregate_order as the counting/summing tool for orders, setting it apart from sibling get/search/pivot 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 concrete usage instructions: omit group_by for a whole-set total, group by a property for grouped totals, and filter returned rows client-side. It does not mention alternatives or exclusions, but the context is clear enough for an agent to know when this tool applies.

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

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

With no annotations provided, the description carries the behavioral burden and does a good job: it discloses the return shape ('Returns set and values; each row has a key, member pks and numeric metrics'), the empty-set behavior ('key: null, zero metrics for an empty set'), and the client-side filtering follow-up. It does not explicitly state that the operation is read-only or side-effect-free, but the counting/summing framing strongly implies it; the added detail still goes well beyond a minimal description.

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

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

Three sentences with no filler: the core action comes first, grouping semantics follow, and output/follow-up guidance closes. Every sentence adds relevant information, and the structure is front-loaded so an agent can quickly decide whether to call the tool.

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

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

This tool has no output schema, so the description adequately explains return values, including the empty-set case and the meaning of row fields. It does not explicitly enumerate the exact allowed values for sum and group_by, but the input schema's enums provide that. The note about filtering rows and using their pks to continue exploring adds useful workflow context. Overall, the description is complete enough 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 0%, so the description must compensate for parameter meaning. It explains pks as 'selected Product objects' and clarifies the role of group_by, which is valuable. However, it uses vague phrases like 'sum a numeric property' and 'group by a property' instead of naming the allowed enum values (stock, id, name), leaving the schema to fill an important gap in precise 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?

The description opens with a specific verb and resource: 'Count the selected Product objects and optionally sum a numeric property.' This clearly identifies an aggregation action on productshare and distinguishes it from generic names like search_product or get_product. The optional grouping and summing are also stated, giving immediate functional orientation.

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 within-tool usage guidance, such as 'Omit group_by for one whole-set total' and 'group by a property,' which is helpful for how to configure the call. However, it does not explicitly explain when to choose this tool over sibling tools like aggregate_order or pivot_* tools, nor does it state prerequisites like 'use after selecting products.' The workflow hint to 'continue exploring' implies context but does not explicitly route the agent away from 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?

With no annotations provided, the description takes on the transparency burden. It discloses that writes are gated by business rules, that rejections return a machine-readable error object ({ code, message }), and that attempts are recorded in the audit log. This adds meaningful behavioral context beyond a mere 'assign' statement, though it stops short of detailing all side effects (e.g., order status change) or authentication requirements.

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

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

The description is two sentences long, front-loaded with the core purpose, and contains no filler. Every sentence adds value: the first identifies what the tool does; the second explains write gating and error behavior.

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 mutation tool with no output schema, the description covers the essential parts: the operation, the pending-order constraint, and error/audit behavior. It does not explain the success return value or permissions, but these gaps are less critical given the simplicity of the tool and the existing 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?

The input schema has zero description coverage (0%), so the description must compensate. It only paraphrases the parameters: 'pending order' implies orderId, and 'person' implies assignee, but it does not explain the expected format of assignee (e.g., user ID, email) or any other constraints beyond the schema's minLength:1. This is insufficient for full 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 clearly states the action ('Assign'), the target ('a pending order'), and the recipient ('a person for fulfilment'). It is distinct from sibling tools like cancel_order, get_order, and search_order, which perform different operations on orders.

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 specifies the usage context: assigning a pending order to a person for fulfilment. It does not explicitly mention when not to use it or compare to alternatives, but the context is clear enough for an agent to identify this as the correct tool for assignment operations.

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

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

With no annotations, the description carries the full burden and discloses important behaviors: writes are gated, errors are machine-readable with code and message, and attempts are audited. It also notes the shipped-order restriction, though it omits what happens on success (e.g., resulting order status) or whether cancellation is reversible.

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 sentences long, front-loaded with the main action, and every phrase contributes value. The gating and audit information is concise and packed with necessary 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?

Given the absence of annotations and output schema, the description covers the essential behavior, an exception, error format, and audit trail. It stops short of describing the success response or the effect on the order, but for a cancellation tool this is quite 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 0%, so the description must compensate, but it only implicitly references orderId via 'Cancel an order' and does not explain 'reason' at all. The purpose of the reason parameter is left entirely to inference, and its format or validation is not mentioned.

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 'Cancel' with a clear resource 'order', and immediately adds a key constraint ('Shipped orders cannot be cancelled'), making the tool's purpose unambiguous and distinct from sibling tools like assign_order or add_order_note.

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

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

Provides an explicit when-not condition for shipped orders, which helps agents avoid misuse. It does not name alternative tools, but the cancellation action is unique among siblings, and the gated-write behavior implies that business rules will be checked.

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

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

No annotations are provided, so the description carries the full burden. It does not disclose behavior such as what happens when the ID is not found (e.g., null vs error), authentication requirements, or return format. The description only restates the basic fetch operation without adding behavioral context beyond what the name and schema imply.

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

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

The description is a single, concise sentence that is front-loaded with the verb and resource. Every word contributes, with no redundant details 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 simple single-record fetch with one parameter, the description adequately explains what the tool does. The lack of output schema and annotations is mitigated by the simple nature of the tool, though it could benefit from noting not-found behavior or return structure.

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

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

The schema description coverage is 0%, but the description compensates by clarifying that 'id' is the primary key. This adds meaningful semantic context to the otherwise bare string parameter, though it does not detail format 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 clearly states the verb 'Fetch', the resource 'Customer', and the method 'by primary key (id)'. This distinguishes it from sibling tools like search_customer and aggregate_customer.

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

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

The description implies usage when you have a specific customer ID and need a single record, but it does not explicitly state when to use this over alternatives like search_customer. No exclusions or comparison to siblings are provided.

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

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

With no annotations, the description carries the full burden. It conveys a read-only fetch action, which is transparent, but does not disclose behavior for missing ids (e.g., error or null) or any other side effects. It adds no extra behavioral traits beyond the basic 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?

The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the action, resource, and lookup method.

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 get-by-id tool with one parameter and no output schema, the description is sufficiently complete. It covers the action and key identifier, though it omits error handling details. Given the low complexity, this is adequate.

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 0% and the schema only defines 'id' as a string. The description adds that 'id' is the primary key, which is a small semantic addition. However, it does not provide format, examples, or constraints, leaving room for ambiguity.

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 fetches a single Note by its primary key (id). It uses a specific verb ('Fetch'), specifies the resource ('a single Note'), and defines the lookup method ('by primary key'), distinguishing it from search or aggregate alternatives.

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

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

The description implies usage: when you have a specific id and need exactly one Note. However, it does not explicitly mention when not to use it or name alternatives like search_note, even though sibling tools exist. The context is clear but lacks explicit exclusions 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?

With no annotations, the description carries the full burden. It discloses that this is a read-only fetch operation via the verb 'Fetch' and that it returns a single Order. However, it does not mention error handling, authentication requirements, or the structure of the returned object, leaving notable behavioral gaps.

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

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

The description is a single sentence that is front-loaded with the verb and purpose. There is no waste, and every word contributes to understanding the tool.

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

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

Given the simplicity of a get-by-id operation, the description covers the core behavior well. However, the lack of an output schema or error behavior leaves some ambiguity about what is returned when the id is valid or not found. Still, it is reasonably complete for a tool of this complexity.

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

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

The schema provides only a bare 'id' string with no description, so the description compensates by clarifying that 'id' is the primary key of the Order. This adds semantic meaning beyond the schema, though it does not provide details on format or constraints. For a single parameter, this is sufficient.

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 'Fetch' with the resource 'Order' and explicitly states 'by primary key (id)', which clearly defines the type of access. This distinguishes it from siblings like search_order, which searches rather than fetches by exact id.

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 'by primary key (id)' gives clear context that this tool should be used when the exact id is known. It does not explicitly name alternatives or exclusions, but the purpose clarity implies the appropriate use case without ambiguity.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It indicates a read operation through 'Fetch' but gives no details on error behavior (e.g., missing id), return structure, or whether the product exists. This is minimal behavioral transparency.

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

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

The description is a single, front-loaded sentence that directly communicates the tool's purpose without any filler. Every word contributes to understanding what the tool does.

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 get-by-id tool with one parameter and no output schema, the description covers the core function adequately. However, without annotations or output schema, it leaves the return shape and not-found behavior unspecified, making it minimally complete but not fully self-sufficient.

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

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

Schema description coverage is 0%, but the description adds the semantic meaning that 'id' is the primary key, which is not present in the schema's raw type definition. It does not provide formats, examples, or related lookup guidance, so it only partially compensates for the schema's lack of descriptive detail.

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

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

The description uses the specific verb 'Fetch' and clearly identifies the resource ('a single Product') and the lookup mechanism ('by primary key (id)'). This distinguishes it from sibling tools like search_product (searching) and aggregate_product (aggregation), as well as from get_order/get_customer/get_note by naming the 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 no guidance on when to use this tool versus alternatives. It does not mention search_product for filtered lookups or clarify that this tool requires a known primary key. Usage context is only implied by the wording, not explicitly stated.

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

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

No annotations are provided, so the description carries the full burden. It discloses that sets are 'reloaded for this session', which hints at session-scoped behavior, but it doesn't explain what 'reloaded' means, whether the operation mutates anything, whether the input arrays are primary key values, or what the output looks like. For a set operation with no annotations, this is a significant gap.

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

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

The description is a single concise sentence that front-loads the operation and resource. It earns its place by adding the primary-key and session-reload context. No wasted words.

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

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

For a set-operation tool with no annotations, no output schema, and 0% schema coverage, the description is too thin. An agent needs to know what the output is (intersected set? count?), whether the operation is read-only, and how the session reload works. The sibling family suggests a pattern, but the description alone doesn't make the tool safely callable.

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 0%, so the description must compensate. It says the sets are 'identified by primary keys', which clarifies that the string arrays contain primary key values, but it doesn't explain the semantics of 'left' and 'right' beyond that, nor the order/duplicate behavior. The description adds some meaning but leaves important parameter semantics 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 states a specific verb ('intersect') and resource ('Customer sets'), and identifies the sets by primary keys. It distinguishes from siblings like union_customer and subtract_customer by naming the set operation, though it doesn't explicitly name those siblings.

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

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

The description implies usage: intersect two Customer sets for this session. It doesn't explicitly state when to use this over alternatives, but the set-operation family (union/subtract/intersect) makes the context reasonably clear. No exclusions or alternative routing are provided.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, but it only adds the vague phrase 'identified by primary keys and reloaded for this session.' It does not state whether the operation is read-only, what side effects occur, or how the resulting Note set is returned.

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

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

The description is a single, front-loaded sentence with no filler; 'intersect two Note sets' appears first and carries the core meaning. The trailing clause is compact but somewhat cryptic, though the overall length is appropriate.

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 has no annotations, no output schema, and 0% schema description coverage, leaving the description as the only invocation context. It fails to define the return value, the exact semantics of left/right, or edge-case behavior, so the agent must make several assumptions.

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 0%, so the description must clarify the left and right string arrays, but it never explicitly says each array contains note primary keys. The phrase 'identified by primary keys' hints at this, yet it remains ambiguous and does not explain expected format, duplicates, or ordering.

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

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

The description states a concrete operation — 'intersect two Note sets' — with a clear resource and action, and the action differentiates it from sibling tools like union_note and subtract_note. However, it does not define what a 'Note set' is or what the returned result represents, so it is not fully self-contained.

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

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

The description offers no explicit guidance on when to use this tool or how it compares to union_note, subtract_note, or aggregate_note. The word 'intersect' implies a use case, but the agent is left to infer selection criteria from the tool name and siblings.

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

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

No annotations are provided, so the description carries the full burden. It mentions that the Order sets are 'reloaded for this session,' which hints at data freshness but does not disclose whether the operation is read-only, what happens on invalid keys, or what the return format is. This is insufficient for a tool with no annotation coverage.

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

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

The description is a single concise sentence with no fluff, front-loading the operation. It is appropriately sized for a simple tool, though it may be under-specified.

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 lack of an output schema and annotations, the description should explain what the tool returns and any edge cases. It does not mention the result of the intersection, so an agent cannot know what to expect. The 'reloaded for this session' note is the only extra context, but it does not complete the picture.

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

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

The schema has 0% description coverage, and the description only vaguely refers to 'primary keys' to identify the Order sets. It does not explain the exact format of the strings, whether duplicates are handled, or how the arrays relate to the 'reloaded' behavior. The description adds minimal meaning beyond the raw parameter 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?

The description clearly states the operation (intersect), the resource (Order sets), and the key aspect that they are identified by primary keys. It distinguishes from sibling tools like union_order, subtract_order, and aggregate_order by naming the intersection operation specifically.

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 does not provide explicit guidance on when to use this tool over alternatives like union_order or subtract_order. It only states what it does, leaving the selection to the agent based on the operation name. No when-not-to-use conditions are given.

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?

There are no annotations, so the description must carry the behavioral disclosure burden. It does add useful context by saying the sets are 'identified by primary keys and reloaded for this session,' suggesting session-scoped behavior rather than persistent mutation. However, it does not disclose whether the operation has side effects, how results are returned, or what happens with duplicate or missing keys.

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 concise sentence that front-loads the core operation ('intersect two Product sets') and then adds the key contextual detail about primary keys and session reloading. Every phrase earns its place, with no filler or repetition.

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

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

Given a simple schema with two array parameters, no output schema, and no annotations, the description gives the essential operation and input semantics. However, it leaves out return value expectations and edge-case behavior such as empty sets, duplicates, or invalid keys, so it is only minimally complete for an agent to invoke it 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?

The schema provides only 'left' and 'right' as string arrays with no descriptions, and schema description coverage is 0%. The description compensates partially by stating that the arrays are Product sets identified by primary keys, which is essential. It does not explain the key format, ordering, or whether duplicates are allowed, leaving some ambiguity.

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: 'intersect two Product sets.' It further clarifies that the inputs are primary keys, which distinguishes this from get/search operations. It does not explicitly contrast itself with union_product or subtract_product, but the set-operation semantics are clear from the name and phrasing.

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

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

The description implies usage: it is for intersecting two Product sets identified by primary keys. However, it gives no explicit guidance about when to choose this over union_product, subtract_product, or aggregate_product, and no exclusions or alternative scenarios. The intended use is inferable but not directly stated.

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

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

With no annotations, the description carries the behavioral burden. It discloses useful behavior: duplicate target identities are removed and direction is conditionally required. However, it does not state whether the operation is read-only, what output shape is returned, or any side effects, leaving important behavioral traits undisclosed.

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: 'Follow customerOrders from a set of Customer or Order.' The two additional sentences add relevant behavioral constraints without padding. It is concise, though brevity comes at the cost of completeness.

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 has two parameters, a nested object, no output schema, and no annotations, so the description must be nearly self-sufficient. It fails to define pks, explain forward/reverse direction semantics, or describe the result format. The deduplication note helps, but an agent cannot reliably determine the full call contract from this description.

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

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

Schema description coverage is 0%, so the description must compensate for undocumented parameters. It explains that source can be a set of Customer or Order and mentions direction's conditional requirement, but it does not clarify the meaning of pks, the values forward/reverse, or how direction affects the result. An agent would struggle to construct a correct call based only on this 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 uses a specific verb and resource: 'Follow customerOrders from a set of Customer or Order.' It also states a key behavior: duplicate target identities are removed. However, it does not differentiate this tool from the sibling traverse_customer_orders, which may perform a similar traversal, leaving some ambiguity about when to choose pivot over traverse.

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 its alternatives such as traverse_customer_orders or the various union/intersect tools. The only usage-related detail is the conditional requirement that direction is needed when both ends have the same type, but this is not contextualized as a tool-selection guideline.

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

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

With no annotations provided, the description must carry the full behavioral disclosure burden. It does mention that duplicate target identities are removed and that direction is conditionally required, which are useful. However, it omits other behaviors such as whether the operation is read-only, what happens if direction is missing when required, or the nature of the returned data. The description adds some transparency but is not comprehensive.

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 concise, consisting of two sentences that front-load the core action and a key constraint. There is no fluff or redundant information, and the structure is easy to scan. It is appropriately sized for the tool's simplicity, though it could afford more detail without becoming verbose.

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 there is no output schema, no annotations, and low schema coverage, the description is thin for the task. It does not explain the return format, any limitations on input size, or error conditions. For a pivot operation that follows links between Orders and Notes, an agent might need more context on how results are presented or how direction affects traversal. The description is minimal and likely insufficient for an agent to confidently invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate by explaining the parameters. It explains that source can be of type Order or Note and that direction is required for same-type sources, but it does not elaborate on the 'pks' structure or the exact meaning of 'forward' and 'reverse'. The description adds minimal value beyond the schema, leaving the pks array semantics to the agent's inference.

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 ('Follow orderNotes') and the resource (orderNotes from a set of Order or Note). It identifies the input types and the need for direction in same-type cases, giving a specific sense of the tool's function. However, it does not explicitly differentiate from the sibling 'traverse_order_notes' or other pivot tools, so it's not a perfect 5.

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

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

The description gives one usage constraint ('Direction is required when both ends have the same type') but does not explain when to choose this tool over alternatives like traverse_order_notes or other pivot functions. There is no mention of use cases, exclusions, or comparative guidance, leaving the agent to infer when to invoke this tool.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It does disclose useful behavior: duplicate target identities are removed and direction is required under certain conditions. However, it does not explain what 'forward' and 'reverse' mean, what the output looks like, or how errors are handled.

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

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

The description is only two sentences and front-loads the core action. Each sentence adds relevant information, including duplicate removal and direction requirements. It is concise without being padded.

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

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

Given the absence of annotations and output schema, the description is insufficiently complete for an agent to confidently invoke the tool. It lacks the meaning of direction values, the shape of returned entities, and any examples or caveats. The tool involves a pivot relationship, which is more complex than a simple lookup, so more context is needed.

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

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

Schema description coverage is 0%, so the description must compensate for the input schema. It partially does by indicating source types ('Order or Product') and the existence of a direction parameter, but it does not define the meaning of 'forward' or 'reverse', nor does it clarify the role of 'pks'. This leaves the agent inferring key 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?

The description uses a specific verb ('Follow orderProducts') and names the resource ('orderProducts') and the valid source types ('Order or Product'). It clearly states the core action. However, it does not explicitly distinguish itself from the sibling 'traverse_order_products', which appears to operate on the same relationship.

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 about when to use this tool versus alternatives such as 'traverse_order_products' or 'get_product'. It only mentions a conditional rule about direction when both ends have the same type, which is a behavioral constraint rather than 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?

With no annotations provided, the description carries the full burden. It discloses that the log is append-only (immutability), contains both applied and rejected actions with actor/params, and is explicitly fail-open and unscoped, which are critical behavioral traits. This is strong transparency, though it omits concerns like pagination or permissions.

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

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

Two short sentences, front-loaded with the main purpose, then a key caveat. No unnecessary 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?

The description gives a good high-level overview but lacks details on filter semantics, return structure, and access controls. Given the absence of an output schema and annotations, these gaps reduce its completeness, though the tool is relatively simple.

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 0%, and the description does not explain the meaning of the 'action' or 'target' parameters or how they interact with the log. Only 'status' is partially clarified by the phrase 'applied and rejected'. This is insufficient compensation for the missing 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 explicitly states 'Read the append-only audit log: every applied and rejected action, with actor and params', which clearly identifies the tool's function and distinguishes it from sibling tools focused on orders, customers, and products. The 'unscoped administrative view' phrase further clarifies its role.

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 communicates that this is an unscoped administrative view, implying it is for admin-level audit use where visibility filters are bypassed. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of full exclusionary guidance.

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

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

With no annotations, the description must carry behavioral disclosure. It does state the operation is read-only ('Read') and scoped to the session, and it indicates there is no server-side filtering by instructing client-side filtering. However, it does not mention pagination, result size limits, or authentication/authorization requirements beyond the vague session-visibility phrase.

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

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

Two sentences, front-loaded purpose in the first, workflow in the second. No filler or redundant schema restatement.

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 tool with no output schema and no annotations, the description covers purpose, scope, and downstream usage. It might be slightly more explicit about returning all visible customers or about pagination, but the essential calling contract 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?

This tool has zero parameters, so the schema conveys all there is. The description's advice about filtering returned objects and passing IDs is not parameter documentation but workflow guidance. Baseline 4 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 clearly states the tool reads Customer objects visible to the session. The verb 'Read' plus the resource 'Customer objects' and the session-scope qualifier make the operation unambiguous. It does not explicitly contrast with get_customer or other search_* siblings, so it stops short of full sibling differentiation.

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

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

It provides a concrete usage pattern: fetch all visible customers, filter client-side, then pass selected IDs to pivot, set, or aggregate tools. This tells an agent when the tool fits in a workflow. It does not explicitly state when not to use it or name alternatives such as get_customer, so there are no 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description is incoherent and does not disclose side effects, read-only behavior, pagination, or any other behavioral traits. The phrase 'visible to this session' hints at scoping but is not elaborated, and the rest of the text is nonsensical.

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 not concise; it is a run-on, garbled sentence that mixes a simple read operation with irrelevant client-side filtering and pivot/aggregate instructions. It is not front-loaded and contains confusing, contradictory guidance. Every sentence fails to earn 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 tool has no output schema and no annotations, the description must explain what the tool returns and how it behaves. It does neither coherently. The garbled text actively harms usability, and the tool cannot be correctly invoked based on this description.

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

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

The input schema has zero parameters, so there is no parameter burden to carry. The description's mention of 'objects visible to this session' adds a minimal semantic hint about implicit scoping, but with no parameters, the baseline is 4. The garbled text does not detract from parameter semantics because there are no parameters to document.

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 is garbled and tautological: 'Read Note objects visible to this session' is the only coherent fragment, but it is immediately followed by nonsensical text ('Filter the returned objects in client-side code, then pass selected IDs to pivot, set or aggregate tools'). It does not clearly state what the tool does, and the name 'read_note' is merely restated. It fails to distinguish itself from sibling tools like get_note or search_note.

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 clear guidance on when to use this tool versus alternatives. The garbled instruction to 'filter the returned objects in client-side code' is misleading and does not explain when to prefer read_note over get_note, search_note, or other siblings. There is no mention of exclusions or alternative tool selection.

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

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

No annotations are present, so the description carries the full burden. It does disclose that the operation is a read, that results are session-scoped, and that there is no server-side filtering. However, it does not mention pagination, result limits, return format details, or authentication assumptions, leaving some behavioral uncertainty for a no-annotation tool.

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

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

Two sentences with no filler. The first sentence states exactly what the tool returns, and the second gives a direct usage workflow. The key information is front-loaded and 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?

With no output schema and no annotations, the description should clarify return values and potential caveats. It says 'Order objects visible to this session,' which describes the result, and the workflow advice helps the agent understand what to do with the output. However, it omits whether the return is a flat array, whether pagination applies, and any error or auth scenarios. For a simple read tool this is close 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?

The tool has 0 parameters, and the schema is an empty object, so the baseline is 4. The description adds context by explaining that filtering is done client-side, which justifies the absence of filter parameters in the schema. This is meaningful clarification beyond the empty 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 resource ('Order objects'), and the plural 'objects' together with 'Filter the returned objects' clearly indicates this is a listing/search tool, distinguishing it from a single-object getter like get_order. It doesn't explicitly name the sibling differentiation, but the meaning 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 provides explicit usage context: retrieve all visible orders, filter client-side, then pass selected IDs to pivot, set, or aggregate tools. This tells the agent how to compose the tool with downstream operations successfully. It doesn't explicitly state when NOT to use it or recommend get_order as an alternative, but the workflow guidance is valuable.

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

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

With no annotations, the description carries the behavioral burden. It discloses that the tool is read-only ('Read'), scoped to the session ('visible to this session'), and returns objects suitable for client-side filtering. It does not describe pagination or possible failure modes, but for a zero-parameter read tool, these are reasonable gaps and the core behavior is transparent.

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, 27 words, zero filler. The core purpose is front-loaded, and the downstream workflow is stated economically. 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 zero-parameter read tool with no output schema, the description covers the essential context: what it reads, the visibility scope, and how the result should be used. It does not describe the exact return structure, but given the tool's simplicity and the empty schema, the description is largely complete for an 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?

The input schema has zero properties, so schema coverage is 100% and the baseline is 4. The description reinforces that no server-side filtering is supported by instructing to filter client-side, which aligns with the empty schema. It adds no unnecessary parameter information.

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

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

The description states a specific verb and resource: 'Read Product objects visible to this session.' It distinguishes itself from sibling search tools by explicitly targeting Product objects and by describing the returned set as session-visible products. However, it does not explicitly contrast itself with get_product or other alternatives, so it earns 4 rather than 5.

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

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

The description gives clear usage context: fetch Product objects, filter them in client-side code, then pass selected IDs to pivot, set, or aggregate tools. This is an explicit workflow that tells the agent when this tool fits. It does not name excluded alternatives or state when not to use it, but the workflow guidance is concrete and useful.

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?

There are no annotations, so the description carries the full burden of explaining behavior. It does mention that sets are 'identified by primary keys and reloaded for this session,' which is a useful detail, but it does not state whether the operation mutates data, returns a new set, or what side effects might occur. The phrase 'reloaded for this session' is also vague and could confuse an agent about statefulness.

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 concise sentence with the core operation front-loaded. The phrase 'and reloaded for this session' adds some behavioral context but is somewhat awkward and not essential for initial identification. Overall it is appropriately short and well-structured.

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

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

With no annotations and no output schema, the description is the only source of behavioral context. It does not describe the return value, whether the operation is read-only, or the exact semantics of 'subtract' in terms of primary keys. For a tool that takes two sets and computes a difference, an agent would need more context to call it 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?

The schema only says left and right are arrays of strings, with no descriptions property coverage. The description adds meaningful meaning by clarifying that the arrays represent Customer sets and that the string elements are primary keys. This is the essential semantic needed to invoke the tool correctly, though it does not explicitly explain the order-sensitivity of left and right.

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 operation ('subtract') and a specific resource ('Customer sets'), making the tool's purpose immediately clear. The sibling set-operation tools (union_customer, intersect_customer, aggregate_customer) are all distinguishable by the verb used. Even though it does not explicitly say 'left minus right', the meaning is clear enough from the verb and context.

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 word 'subtract' implies this is for set-difference operations, and the sibling names give contextual contrast with union/intersect tools. However, there is no explicit guidance on when to choose this tool versus alternatives, no examples, and no mention of when not to use it. The usage is implied rather than stated.

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

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

With no annotations, the description carries the behavioral disclosure burden. It reveals that inputs are identified by primary keys and that notes are 'reloaded for this session,' which is useful context beyond the schema. However, it does not clarify whether the operation mutates session state, is read-only, or what side effects 'reloaded' implies.

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 14-word sentence with no filler. It front-loads the core operation and then adds the key detail about primary keys and reloading. Every phrase 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?

This simple tool has no annotations, no output schema, and no property descriptions, so the description must carry heavy context. It omits the result type or shape, the order of subtraction (left minus right vs right minus left), and any effect on the session beyond vaguely saying 'reloaded for this session.'

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 0%, so the description must compensate. The phrase 'identified by primary keys' adds meaning to the left and right arrays as sets of note primary keys. However, the description does not explicitly define 'left' as the source set and 'right' as the set to remove, leaving the operand order ambiguous.

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 operation ('subtract') and resource ('Note sets'), and the sibling list includes subtract_customer/order/product, so 'subtract_note' is distinguishable by resource. It could be clearer that 'subtract' means set difference in a specific direction, but the verb and noun provide enough purpose.

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 context is implied by the phrase 'subtract two Note sets' and the sibling naming pattern (union_note, intersect_note, subtract_note), but there is no explicit when-to-use or when-to-use-alternative guidance. An agent could infer this is for set difference operations on Note collections, but no exclusions are stated.

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

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

With no annotations provided, the description must disclose behavioral traits, but it only says the sets are 'reloaded for this session.' It does not state whether the operation is read-only, whether it has side effects, what permissions are needed, or what the return value represents.

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, concise sentence with no fluff. It packs the core operation, the resource type, and a behavioral note about reloading into one line. However, it could be more structured to highlight key aspects like operand order and result.

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

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

Given no output schema and no annotations, the description is thin. It omits any indication of what the result is (a set of order keys? full order objects?), whether the operation mutates data, or any prerequisites. The 'reloaded for this session' hint is vague and not expanded.

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 0%, so the description must clarify parameter meaning. It mentions 'primary keys,' which implies the array elements are keys, but it does not explain the semantics of left vs. right or whether the operation is symmetric. This leaves the agent guessing about operand roles.

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 ('subtract') and resource ('Order sets'), and the set-operation meaning is clear from the tool name. However, it does not explicitly state that 'left' is the set from which 'right' is subtracted, leaving room for ambiguity about operand order.

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 versus siblings like union_order, intersect_order, or subtract_customer. An agent cannot tell from the description whether this is appropriate for a given scenario or how it differs from similar set operations.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It mentions 'reloaded for this session,' which hints at a data-loading behavior, but does not state whether the operation is read-only, what happens with missing keys, whether order matters, or what the return value looks like. This is a significant gap for a set operation with no schema coverage.

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

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

The description is a single, front-loaded sentence with no fluff. It directly states the purpose and the key identification mechanism. It is appropriately concise, though it could have added more detail without losing conciseness.

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 set-operation tool with two array parameters, no annotations, and no output schema, the description is notably incomplete. It does not explain the result format, error behavior, or edge cases (e.g., duplicate keys, empty sets). An agent would need to infer too much to call it correctly and interpret the outcome.

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

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

The schema provides two arrays of strings with no descriptions (0% coverage). The description clarifies that these arrays are 'identified by primary keys,' giving meaning to the parameters. However, it does not explain the exact semantics of left vs. right (e.g., which is the base set) or any formatting requirements. It partially compensates for the schema gap but not fully.

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 action (subtract) and the resource (Product sets), and clarifies that they are identified by primary keys. It differentiates from siblings because it targets Product specifically, though it doesn't explicitly contrast with union/intersect. The meaning of 'subtract' is implied but not formally defined (e.g., set difference), so it's clear but not fully precise.

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 tool is for subtracting Product sets, which inherently distinguishes it from union/intersect and from other entities. However, it does not explicitly state when to use it over alternatives or provide exclusions. The context is clear enough for an agent to infer usage, but lacks explicit guidance.

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

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

With no annotations, the description carries the full burden. It usefully discloses that the instance's properties are a snapshot and not authoritative, and that direction is inferred from source.type. It omits other behavioral facts an agent would want: what the traversal returns, whether it re-reads current state, and any pagination or permission behavior.

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

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

Three dense sentences with no filler; the link identity and cardinality are front-loaded, followed by the input provenance and the direction rule.

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

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

No output schema and no annotations, and the description never states what a traversal yields (presumably a list of related Orders) or its size/pagination behavior. It adequately covers inputs and direction semantics but leaves the return side underspecified for a nested-object tool.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: it explains the origin of `source` (from get/search), that its properties are a snapshot, and the direction-inference rule plus the constraint that an explicit direction must agree with source.type. This is substantive meaning the schema does not encode.

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 (traverse) and a precisely named resource (the Customer → Order link "customerOrders"), including its one-to-many cardinality. An agent can distinguish this from sibling traversal tools like traverse_order_products or traverse_order_notes 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?

Tells the agent where the required `source` must come from (an instance returned by get or search) and how direction is resolved. It does not explicitly contrast with get_order/search_order alternatives, so it stops short of full when/when-not guidance.

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

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

No annotations exist, so the description carries the behavioral burden. It does add a meaningful caveat that source properties are a snapshot and not authority, which is genuinely useful for an agent. But it doesn't disclose whether any data is mutated, authorization constraints, pagination of the one-to-many result, or what the traversal returns. Given no annotations, more behavioral disclosure is warranted, so a 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?

Four short clauses, no wasted words, and the key constraint (snapshot not authority) is front-loaded. Slightly elliptical but 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 2-parameter traversal tool with no output schema and no annotations, the description is nearly complete: it explains the link, the source requirement, the snapshot caveat, and direction resolution. The one missing element is what the one-to-many traversal actually returns (a list of Notes) and whether it paginates, which would help an agent use 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 0%, so the description is the only place meaning is added. It explains that 'source' must be a full instance (with type/pk/properties), that its properties are a non-authoritative snapshot, and that 'direction' is inferred from source.type unless explicitly provided. This covers the critical semantic for 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?

States a specific verb (traverse) and resource (the Order→Note link 'orderNotes'), explicitly calls out the one-to-many cardinality, and distinguishes itself from sibling traversal tools by naming the link. An agent can differentiate it from traverse_customer_orders or traverse_order_products immediately.

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

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

Tells the agent to pass an instance returned by get or search, which is a clear usage precondition. Direction inference rules are also stated. However, it doesn't mention when to prefer this over get/aggregate siblings or any exclusions, keeping it 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?

With no annotations the description carries the full burden, and it does add real behavior: the passed properties are a snapshot, not authoritative, and direction is inferred from source.type with explicit direction required to agree. It still omits whether the operation is read-only, what it returns, and pagination/limits for a many-to-many traversal.

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

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

Three compact sentences, front-loaded with the relationship and its cardinality. Slightly dense and abbreviation-heavy, but no sentence is wasted.

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

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

The input side is well covered, but with no output schema and no statement of what a traversal returns (related Product or Order instances, counts, pagination), the description leaves the agent guessing about results for a nested, many-to-many 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 0%, so the description must compensate, and it does: 'source' must be an instance from get/search and its properties are snapshot-only, while 'direction' is normally derived from source.type and must agree if supplied. It adds meaning well beyond the bare enum, though it doesn't explain direction values themselves.

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

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

Names a specific verb (traverse), the exact relationship ('orderProducts', many-to-many) and its endpoints, which cleanly separates it from siblings like traverse_customer_orders and traverse_order_notes. An agent can identify the operation without opening the schema.

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

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

States the prerequisite clearly ('Pass an instance returned by get or search'), which tells the agent what to feed it. It does not state when to prefer this over alternatives such as search_product, but the traversal-vs-search distinction is reasonably implied by the tool name and the snapshot caveat.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It goes beyond a bare operation by mentioning primary-key identification and that sets are 'reloaded for this session', which hints at a session-level side effect. However, it does not clarify whether session state is mutated, what happens to the result, or whether the operation is reversible or safe.

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 sentence with no filler, placing the main verb and resource first. It is appropriately sized for a simple two-parameter tool and every phrase 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 two-parameter tool, the definition is close to adequate, but with no output schema and no annotations the agent cannot tell whether the tool returns the union or mutates session state by reloading. The meaning of 'reloaded for this session' is underspecified, and the exact item format within the arrays is only inferred.

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 0%, so the description must compensate for the bare string-array parameters. It partially does by indicating the inputs are Customer sets identified by primary keys. It does not define left/right individually, specify the key format, or address uniqueness/order, leaving some ambiguity.

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 opens with 'union two Customer sets', a specific verb/resource pairing that matches the tool name. It adds that the sets are 'identified by primary keys', clarifying what the operation acts on. It does not explicitly distinguish this from sibling tools like intersect_customer or subtract_customer, so full sibling differentiation is absent.

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

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

There is no explicit statement about when to use union_customer versus intersect_customer, subtract_customer, or aggregate_customer. The usage is only implied by the word 'union' and the surrounding sibling-tool naming. This gives a competent agent the basic idea but no stated alternatives or 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'reloaded for this session' but does not clarify whether this is a read-only operation, whether any state changes occur, or what the exact output format is. The lack of detail about side effects or return behavior leaves significant gaps for a tool with no annotation coverage.

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

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

The description is a single sentence with no redundant words. It leads with the action ('union two Note sets') and adds the key detail about primary keys. It is appropriately concise for the simple operation it describes, though it could benefit from a bit more specificity without becoming verbose.

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

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

For a tool with no annotations, no output schema, and parameters with 0% schema description coverage, the description is insufficiently complete. It does not explain what the tool returns (e.g., a list of Note objects or just IDs), what 'reloaded for this session' means in practice, or any error conditions. An agent would struggle to fully understand the tool's behavior and expected output from this description alone.

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

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

The schema has 0% description coverage, so the description must compensate. It adds that the arrays contain 'primary keys', which clarifies that the strings are identifiers for notes, not arbitrary values. However, it does not specify the format of the keys, whether they must be unique, or any constraints on the arrays. This is helpful but minimal, leaving some ambiguity.

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 ('union') and resource ('Note sets'), and clarifies the input as primary keys. It distinguishes from sibling tools like union_customer or intersect_note by focusing on Note sets, though the phrase 'reloaded for this session' is ambiguous and could confuse agents about the actual output.

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 versus alternatives like intersect_note or subtract_note. The usage is only implied by the name 'union' and the description, but there is no explicit mention of conditions, exclusions, or alternative tools. An agent must infer the intended scenario.

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

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

No annotations are provided, so the description carries the burden. It does add some behavioral context by saying the items are 'identified by primary keys and reloaded for this session', which suggests a session-scoped, non-persistent operation. However, it does not disclose whether the operation mutates anything, deduplicates results, or what the return value looks like.

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 efficient sentence with no filler. The core verb and resource are front-loaded, and the clarifying detail about primary keys and session reloading is added without bloat.

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

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

With no output schema and no annotations, the description should explain what a caller receives after the union. It does not describe the return format, duplicate handling, or side effects, and the phrase 'reloaded for this session' is left ambiguous. The tool is simple, but important invocation-relevant detail 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 0%, so the description must compensate. It partially does by indicating both parameters are Order sets identified by primary keys. However, it does not explicitly map 'left' and 'right' to the two sets or explain string format, duplicates, or ordering expectations.

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

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

The description states a specific operation ('union'), a specific resource ('Order sets'), and clarifies that inputs are primary keys. This clearly distinguishes union_order from sibling tools like intersect_order, subtract_order, and union_customer.

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

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

There is no explicit guidance about when to use this tool versus alternatives, such as intersect_order or union_customer. The description implies a combine/merge use case but never states when-not-to-use or points to a sibling.

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?

In the absence of annotations, the description does add useful behavioral context: the inputs are primary keys, and the result is 'reloaded for this session,' implying session-local state. However, it does not clarify whether the operation mutates session state, what the return value is, or whether anything is persisted, leaving important risk factors ambiguous.

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 with no filler. It states the operation first, then the input identification method, then the session scope. 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 tool with no annotations and no output schema, the description leaves out the return value and the exact side effects of 'reloaded for this session.' An agent cannot confidently know whether calling union_product returns the merged set, updates a session, or overwrites existing state. The core input semantics are covered, but the overall contract is incomplete.

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 0% schema description coverage, the description compensates meaningfully by explaining that both `left` and `right` arrays are Product sets identified by primary keys. Without this, the schema alone would suggest only 'arrays of strings.' It could still be more precise about key format or duplicate handling, but the essential semantic gap is closed.

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 a specific operation ('union') applied to a specific resource ('Product sets'), which distinguishes it from sibling operations like intersect_product, subtract_product, and union_customer/order/note. It also adds that the sets are identified by primary keys, so 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 usage is implied: an agent would choose this tool when it needs to union two product sets. However, the description gives no explicit guidance about when to prefer it over alternative set operations or where the input product sets would come from, and it does not mention any exclusions.

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