Server Quality Checklist

Tool Scores

• add_order_noteB
  3.3/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness2/5

  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.

  Parameters1/5

  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.

  Purpose5/5

  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.

  Usage Guidelines2/5

  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.

• aggregate_noteB
  3.3/5.0
  Behavior2/5

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

  No annotations are present, so the description must carry the transparency burden. It discloses the query-time nature and counting/summing behavior, but leaves return format and the numeric property trigger unspecified, and omits read-only/safety details.

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

  Conciseness5/5

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

  The description is a single front-loaded sentence with the scope and resource stated immediately. The additional 'query-time' clause provides useful context without bloat.

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

  Completeness2/5

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

  With no output schema and no documentation of the filter parameter or grouping output shape, the description is incomplete. The ambiguous 'summing a numeric property' is especially problematic for an agent needing to invoke the tool.

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

  Parameters2/5

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

  Schema description coverage is 0%, yet the description only vaguely references 'a property' for group_by and omits the filter parameter entirely. The mention of 'optional summing a numeric property' introduces a capability not reflected in the schema, misleading the agent.

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

  Purpose5/5

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

  The description uses specific verbs 'Group' and 'counting' to state the aggregation operation on Note objects. It clearly distinguishes from sibling search/get/traverse tools by targeting aggregation specifically.

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

  Usage Guidelines3/5

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

  The description implies usage through the aggregation purpose but does not explicitly name alternatives or exclusions. The 'Query-time aggregation' clause hints at a differentiation from precomputed data, but there is no direct when-to-use guidance.

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

• get_productB
  3.3/5.0
  Behavior2/5

  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.

  Conciseness5/5

  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.

  Completeness3/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines2/5

  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.

• search_customerB
  3.4/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden. It discloses useful behavioral traits: 'All filter fields are optional and match by equality' and results are 'scoped by the model-attached visibility policy'. However, it does not describe the return format, pagination, or behavior when no filters are supplied, leaving gaps.

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

  Conciseness5/5

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

  The description is two concise sentences with no unnecessary words. The action and resource are front-loaded, and the behavioral details are efficiently conveyed.

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

  Completeness4/5

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

  For a simple tool with three optional parameters and no output schema, the description covers the key semantics: optional equality filters and visibility scoping. It does not explicitly state that it returns a list of Customer objects, but the verb 'Search' implies a list. Given the low complexity, it is fairly complete, though explicit mention of the return structure would improve it.

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

  Parameters3/5

  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 statement that all filter fields are optional and match by equality adds meaning beyond the bare property names. However, it does not elaborate on each field beyond its name, and no additional details like allowed formats or examples are provided.

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

  Purpose4/5

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

  The description clearly states the action ('Search') and the resource ('Customer objects'), and adds context that a customer is 'of the merged company'. It clearly differentiates from other search tools by resource name, but does not explicitly contrast with siblings such as get_customer or aggregate_customer.

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

  Usage Guidelines2/5

  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 search tool versus alternatives like get_customer or aggregate_customer. The only usage-related information is about filter optionality and equality matching, which pertains to parameter usage, not tool selection.

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

• aggregate_customerA
  3.5/5.0
  Behavior3/5

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

  The description adds the key behavioral insight that 'nothing is precomputed', but it does not explicitly state that the operation is read-only or describe what happens with filters. Since no annotations are provided, the description carries this burden, but it is only partially met.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence with no fluff. It communicates the core action and a critical behavioral trait efficiently.

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

  Completeness2/5

  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 is incomplete. It does not specify the return format or how the optional sum is configured, and it does not explain the role of the filter parameter. The description covers the basic grouping idea but leaves significant operational details ambiguous.

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

  Parameters2/5

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

  Schema coverage is 0%, so the description must compensate for parameter meaning. It explains that grouping is done 'by a property', but the 'optionally summing a numeric property' feature has no corresponding parameter in the schema, leaving agents confused about how to invoke it. The description adds minimal value for the existing parameters.

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

  Purpose5/5

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

  The description clearly states the verb 'Group' with the resource 'Customer objects', and specifies the actions 'counting each group' and 'optionally summing a numeric property'. This distinguishes it from sibling search/get tools and other aggregate tools by explicitly scoping to Customer objects.

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

  Usage Guidelines3/5

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

  The description implies usage for aggregating customer data and notes 'Query-time aggregation', but it does not explicitly state when to use this versus search_customer or other aggregate tools, nor does it mention alternatives or exclusions.

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

• search_productA
  3.6/5.0
  Behavior3/5

  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 important behavioral details: results are scoped by the model-attached visibility policy, and filters match by equality. However, it doesn't mention potential limits, ordering, or return format, which would improve transparency for a search operation.

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

  Conciseness5/5

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

  The description is two sentences long, front-loaded with the core purpose, and every sentence adds value. It avoids repetition and is appropriately sized.

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

  Completeness4/5

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

  For a simple search tool with three optional filters and no output schema, this description provides the essential information: what it searches, how filters work, and session scoping. It doesn't explain pagination or result limits, but these are not necessarily critical for this tool's usage. Overall, it is sufficiently complete for most use cases.

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

  Parameters3/5

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

  The schema has three parameters (id, name, stock) with no individual descriptions, so the description's statement that all filters are optional and match by equality adds meaningful collective semantics. It does not, however, provide per-parameter details beyond types already in the schema, so overall parameter guidance is moderate.

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

  Purpose4/5

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

  The description clearly states the tool searches for Product objects from the ERP item master, using a specific verb ('Search') and resource ('Product objects'). While it doesn't explicitly differentiate from sibling tools like get_product or aggregate_product, the name and scope make its purpose unambiguous.

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

  Usage Guidelines3/5

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

  The description explains that all filter fields are optional and match by equality, giving clear context on how to use the search. However, it does not provide explicit guidance on when to choose this tool over alternatives like get_product (for single fetch) or aggregate_product (for analytics), so usage guidance is implied rather than explicit.

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

• aggregate_orderA
  3.8/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the burden of behavioral disclosure. It adds one useful trait ('Query-time aggregation — nothing is precomputed'), but it does not state whether the operation is read-only, describe the response format, mention performance considerations, or note any required permissions. This gives some transparency but not enough for a 4.

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

  Conciseness5/5

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

  The description is two sentences long, front-loaded with the core action ('Group Order objects by a property'), and the second sentence adds a distinct behavioral note about query-time computation. Every word earns its place, with no redundancy.

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

  Completeness3/5

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

  The tool has three parameters including a nested filter object and no output schema. The description covers the core grouping and summing behavior but gives no guidance on how to use the filter or what the result structure looks like. While adequate for a basic sense of the tool, it leaves gaps for an agent aiming to invoke it correctly.

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

  Parameters2/5

  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 explains the conceptual meaning of grouping and summing, but it omits the 'filter' parameter entirely and does not enumerate which property values are valid for group_by beyond what the schema enums already provide. This is only partial compensation for the undocumented parameters.

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

  Purpose5/5

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

  The description uses a specific verb ('Group') and resource ('Order objects'), clearly distinguishing this aggregation tool from sibling search/get tools. It further specifies the output behavior (counting each group, optionally summing a numeric property), making the purpose unmistakable.

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

  Usage Guidelines4/5

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

  The description states this is a query-time aggregation and that nothing is precomputed, implying it should be used when live aggregated data is needed. However, it does not explicitly name alternative tools (like search_order or get_order) or provide exclusion criteria, so it falls short of fully explicit 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.

• get_customerA
  3.8/5.0
  Behavior2/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines3/5

  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.

• get_noteA
  3.8/5.0
  Behavior3/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines3/5

  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.

• search_orderA
  3.8/5.0
  Behavior4/5

  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 discloses that filter fields match by equality and that results are scoped by a visibility policy—both non-obvious behaviors. It does not explicitly state read-only status, but 'Search' implies a non-mutating operation. This is good but not complete, as it omits potential details like pagination or result shape.

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

  Conciseness5/5

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

  The description is concise and front-loaded with the core purpose. It uses three short sentences that each add value: purpose, filter behavior, and visibility scoping. No redundant or fluff content appears.

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

  Completeness4/5

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

  For a search tool with no output schema and no annotations, the description covers essential aspects: what is searched, how filters work, and a crucial session-scoping detail. It does not mention return format or pagination, but the tool name and typical search semantics make these less critical. Given the low complexity of the parameters, this is reasonably complete.

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

  Parameters3/5

  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 statement 'All filter fields are optional and match by equality' adds meaningful behavior about how parameters work. However, it does not explain the semantics of individual fields beyond their names, leaving the agent to infer meaning. This is adequate but not thorough.

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

  Purpose5/5

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

  The description clearly states the tool's function with a specific verb+resource: 'Search Order objects'. The parenthetical 'A sales order, unified across both legacy systems' adds valuable context that distinguishes it from other order-related tools like get_order. This is a precise and unambiguous purpose statement.

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

  Usage Guidelines2/5

  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 alternative search/get tools. There is no mention of alternatives like get_order for fetching a single order, or any scenario-based recommendations. The only usage-related information is that filters are optional and equality-based, which is more about parameter behavior than usage context.

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

• aggregate_productA
  3.9/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the transparency burden. It adds a meaningful behavioral detail: 'Query-time aggregation — nothing is precomputed' implies real-time results. However, it does not disclose other aspects such as read-only nature, performance implications, or output constraints.

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

  Conciseness5/5

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

  Two compact sentences, front-loaded with the main action and optional modifier. No filler or repetitive information; every word contributes to understanding.

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

  Completeness3/5

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

  For a tool with a nested filter object, no output schema, and no annotations, the description gives a general sense of the output (group counts and optional sum) but omits filter semantics and result format details. It is adequate for the core aggregation but lacks completeness for advanced usage.

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

  Parameters3/5

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

  The description explains the role of group_by ('by a property') and sum ('summing a numeric property'), which complements the schema's enums. But it does not mention the filter parameter at all, leaving that aspect to the schema. Since schema description coverage is 0%, the description only partially compensates.

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

  Purpose5/5

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

  The description clearly states a specific verb+resource: 'Group Product objects by a property' and explains the counting and optional summing. This uniquely identifies the tool's function and distinguishes it from similar tools targeting other resources like Customer, Order, or Note.

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

  Usage Guidelines4/5

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

  The description communicates the core use case: query-time aggregation for grouping/counting/summing. It does not explicitly exclude cases or compare with search_product or other aggregate tools, but the resource-specific wording makes when to use it clear.

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

• read_audit_logA
  4/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness3/5

  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.

  Parameters2/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• search_noteA
  4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the burden and provides useful behavioral details: filters match by equality, all fields are optional, and results are scoped by the visibility policy. This goes beyond a bare 'Search' statement, though it does not cover return format or pagination.

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

  Conciseness5/5

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

  The description is three concise sentences with no fluff. The first defines the resource, the second explains filter behavior, and the third discloses visibility scoping. Every sentence adds value.

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

  Completeness4/5

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

  Despite lacking an output schema, the description covers purpose, resource definition, filter semantics, and security scoping. It does not mention return type or pagination, but for a simple search with three optional string filters, this is reasonably complete.

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

  Parameters3/5

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

  Schema coverage is 0% and parameters are described only by name (id, text, author). The description adds that all filters are equality-based and optional, which is useful but generic. Field-specific semantics are not expanded upon, though property names are self-explanatory.

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

  Purpose5/5

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

  The description clearly states the tool searches Note objects and defines what a Note is ('A triage note — state no source system has a table for'), distinguishing it from siblings like get_note or aggregate_note. The verb 'Search' is specific and matches the tool's name.

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

  Usage Guidelines3/5

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

  The description implies usage through 'All filter fields are optional' but does not explicitly state when to use search_note versus alternatives such as get_note for fetching by ID. No exclusions or alternative tools are mentioned, so guidance is only implicit.

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

• assign_orderA
  4.1/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters2/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• cancel_orderA
  4.1/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters2/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• get_orderA
  4.2/5.0
  Behavior3/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• traverse_customer_ordersA
  4.2/5.0
  Behavior3/5

  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 core traversal behavior and direction semantics but does not mention pagination, ordering, error handling, or explicit read-only guarantees. It is functional but lacks richer behavioral context.

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

  Conciseness5/5

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

  Two compact sentences cover purpose and direction logic with no redundancy. The most important information (link and direction) is front-loaded.

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

  Completeness4/5

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

  For a simple traversal tool with no output schema, the description adequately explains inputs and expected results. It lacks details on result format or edge cases, but the core usage is well covered.

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

  Parameters4/5

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

  The schema provides only types and an enum, but the description adds crucial meaning: pk's role depends on direction, and direction determines traversal direction. This significantly clarifies parameter usage beyond the schema.

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

  Purpose5/5

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

  The description clearly states the tool traverses the Customer → Order link 'customerOrders' (one-to-many), with explicit direction semantics. It distinguishes itself from sibling traversal tools by naming the specific relationship.

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

  Usage Guidelines4/5

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

  Provides clear direction-specific instructions (which pk to pass and what objects are returned), effectively guiding when to use it. However, it does not explicitly mention alternatives or exclusions (e.g., when to prefer direct get/search tools over traversal).

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

• traverse_order_productsA
  4.2/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden but covers only the core traversal behavior. It explains how the direction parameter changes the result but does not mention return format, error handling, or whether it is read-only.

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

  Conciseness5/5

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

  The description is two compact sentences, front-loading the purpose and then providing direction-specific details. Every sentence adds clear value with no redundancy.

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

  Completeness4/5

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

  Given the tool's low complexity (2 params, no output schema), the description adequately covers the main use cases and expected result types. It omits edge cases like missing records or response structure but remains sufficient for a straightforward traversal tool.

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

  Parameters4/5

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

  Schema coverage is 0%, so the description must compensate. It effectively explains the meaning of direction (forward/reverse) and the role of pk dependent on direction, which goes well beyond the raw schema. It could add detail on pk format but is substantially helpful.

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

  Purpose5/5

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

  The description clearly states the tool traverses the Order → Product many-to-many link 'orderProducts', with direction-specific behavior. This specific resource and action distinguish it from sibling traversal tools like traverse_customer_orders and traverse_order_notes.

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

  Usage Guidelines4/5

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

  The description explains both forward and reverse usage with concrete examples (pass Order pk or Product pk). It provides clear context for when to use each direction, though it does not explicitly contrast with alternative traversal tools.

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

• traverse_order_notesA
  4.3/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the burden of behavioral disclosure. It explains the core behavior (pass pk, get linked objects) and mentions the one-to-many nature, but doesn't cover edge cases like empty results, error handling, or whether the operation is read-only. This is adequate but not rich.

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

  Conciseness5/5

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

  The description is two sentences, highly concise, and front-loaded with the link name and relationship. Every word contributes to understanding the tool's purpose and usage, with no filler or redundancy.

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

  Completeness4/5

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

  For a simple 2-parameter traversal with no output schema, the description covers the essential usage and behavior. It lacks explicit details about return format or error behavior, but 'get linked Note objects' reasonably implies the response. Overall, it's nearly complete for the tool's complexity.

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

  Parameters5/5

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

  The description adds significant meaning to both parameters: it clarifies that pk is the Order or Note primary key depending on direction, and explains the effect of choosing 'forward' vs 'reverse'. This goes well beyond the raw schema, which only provides a generic 'pk' and an enum.

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

  Purpose5/5

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

  The description clearly states the tool traverses the Order→Note link 'orderNotes', a one-to-many relationship, and explains both directions. This distinguishes it from sibling traversal tools like traverse_customer_orders or traverse_order_products by naming the specific entities and link.

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

  Usage Guidelines4/5

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

  The description provides explicit instructions for both directions: forward requires an Order pk, reverse requires a Note pk. This gives clear context on when to use each mode, though it doesn't explicitly mention alternatives or when not to use the tool.

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