Server Quality Checklist

Tool Scores

• update_itemA
  4/5.0
  Behavior1/5

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

  The description explicitly encourages non-idempotent operations such as 'SET count = count + :inc' and ADD, but annotations declare idempotentHint=true. This is a direct contradiction, undermining trust in the tool's behavioral contract.

  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 well-structured with a clear lead, bullet lists for usage, and a returns section. Every sentence serves a purpose, and the length is appropriate for the tool's complexity.

  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?

  Combined with a rich schema and output schema, the description covers core selection, supported operations, and the return format. It would be a 5 if not for the idempotency contradiction and the omission that UpdateItem can create an item if the key does not exist.

  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?

  Even though schema description coverage is reported as 0%, the description gives practical examples of update expression syntax and supported operations (SET, REMOVE, ADD, DELETE). It does not elaborate on condition_expression or expression_attribute_names, but those are described in the input 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 first sentence clearly specifies the verb ('Update') and the resource ('specific attributes of an item in a DynamoDB table'), and adds scope by noting it does not replace the entire item. This distinguishes it from sibling tools like add_item and delete_item.

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

  Usage Guidelines5/5

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

  Dedicated 'When to use' and 'When NOT to use' sections provide explicit selection guidance. It names add_item for full item replacement and bulk operations for multi-item updates, directly addressing alternatives.

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

• create_tableA
  4.4/5.0
  Behavior4/5

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

  Annotations already indicate non-read-only, non-idempotent, and non-destructive behavior. The description adds valuable context: default to PAY_PER_REQUEST billing, asynchronous nature implied by 'monitor until ACTIVE,' and the return shape. It does not explicitly mention provisioning behavior or failure states, but it goes beyond annotations meaningfully.

  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 compact and well-organized with clear headings: purpose, when to use, when not to use, and returns. Every sentence earns its place; no fluff or repetition of schema details.

  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 creation tool with output schema and annotations, the description covers the essential workflow: create, check existing tables, monitor with describe_table, and know what to expect in the response. It omits edge cases like provisioned capacity requirements or key type specifics, but those are covered by the input schema, so the overall picture is complete enough.

  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 already provides rich descriptions for all parameters (table_name, partition_key, sort_key, billing_mode, capacity units, key types, tags). The description adds the key default (PAY_PER_REQUEST) and clarifies that sort key is optional, but does not compensate for the undocumented parts of the schema wrapper. This is adequate but not exemplary.

  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 opens with a specific verb+resource phrase: 'Create a new DynamoDB table.' It further defines scope (partition key, optional sort key, default billing mode), clearly distinguishing it from siblings like list_tables, describe_table, and create_gsi.

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

  Usage Guidelines5/5

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

  Explicit 'When to use' and 'When NOT to use' sections provide clear guidance. It names alternatives (list_tables, describe_table) for checking pre-existing tables and for monitoring progress to ACTIVE status, which is exactly the kind of decision support an agent needs.

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

• describe_tableA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds value by specifying the exact return contents (key schema, indexes, billing mode, item count, size) and the status values, which is useful beyond the annotations.

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

  Conciseness4/5

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

  The description is well-structured with clear sections for purpose, usage, and returns. It is longer than the minimal example but every sentence provides useful information and it is front-loaded with the main purpose.

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

  Completeness5/5

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

  Given the tool is a simple read-only describe operation with one parameter and an output schema, the description is thorough: it covers what data is returned, when to use it, and alternatives. No critical gaps.

  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?

  There is only one parameter, table_name, which has a clear description in the schema. The tool description doesn't explicitly mention the parameter but the context ('about a DynamoDB table') makes it obvious. Schema coverage is effectively high, so baseline 3 is appropriate.

  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 opens with a specific verb+resource: 'Get detailed information about a DynamoDB table's schema and configuration.' It clearly lists the returned elements and explicitly distinguishes from sibling list_tables by saying when NOT to use it.

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

  Usage Guidelines5/5

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

  The description includes explicit 'When to use' and 'When NOT to use' sections with concrete scenarios (e.g., checking key schema before querying, verifying GSIs, checking status) and names the alternative tool (list_tables). This is exactly the level of guidance required.

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

• create_gsiA
  4.5/5.0
  Behavior4/5

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

  The description discloses that 'Index creation is asynchronous — use describe_table to monitor progress', a critical behavior beyond the annotations. It also notes the prerequisite that 'The table must be in ACTIVE status' and states the return value confirms initiation. This adds meaningful context beyond the structured annotations, though it could mention potential delays or failure modes.

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

  Conciseness5/5

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

  The description is well-organized into a main paragraph, explicit 'When to use'/'When NOT to use' sections, and a 'Returns' line. Every sentence earns its place, with no redundant content. It is concise yet complete.

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

  Completeness5/5

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

  Given the output schema and annotations, the description covers essential context: the table's required status, async behavior, monitoring via describe_table, and alternative conditions. It fully equips an agent to decide when and how to invoke the tool, and the return type is stated. No major gaps are apparent.

  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 does not enumerate any parameters (table_name, index_name, partition_key, etc.), leaving that to the schema. The schema's top-level 'input' parameter has 0% description coverage, but nested properties are well-described. The description adds conceptual context (e.g., 'non-primary-key attributes') but does not explicitly connect parameters to usage, so it only partially compensates for the low coverage.

  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 'Create a Global Secondary Index (GSI) on a DynamoDB table' with a specific verb and resource. It also explains that GSIs enable querying on non-primary-key attributes, distinguishing it from table creation and other sibling tools like create_table or describe_table.

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

  Usage Guidelines5/5

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

  The description includes explicit 'When to use' and 'When NOT to use' sections, providing concrete conditions such as 'To enable queries on attributes that aren't part of the primary key' and 'If a suitable GSI already exists (check with describe_table first)'. It also names describe_table as an alternative for monitoring and pre-checking.

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

• list_tablesA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds pagination support details (next_table_name) and notes the region scope, which goes beyond annotations. It doesn't mention rate limits or other edge cases, but for a simple read-only list operation, this is adequate.

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

  Conciseness5/5

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

  The description is well-structured with a clear opening sentence, a 'When to use' section, and a 'Returns' section. It is appropriately sized and every section serves a purpose, providing essential information without unnecessary fluff.

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

  Completeness5/5

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

  For a simple list tool with strong annotations and an output schema, the description is complete. It states the resource (DynamoDB tables), scope (AWS region), pagination behavior, and the return format (table_names, count, next_table_name). It also gives usage context relative to sibling tools, making it fully adequate for agent invocation.

  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 input schema provides detailed descriptions for both parameters (limit, exclusive_start_table_name), so the agent has the needed semantics. The description adds context about pagination ('next_table_name for pagination') which complements the schema, but it doesn't explicitly explain the parameters themselves. Given the schema description coverage signal is 0% for the tool description, the description does not compensate fully, but the schema itself covers the 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 'List all DynamoDB tables in the configured AWS region' with a specific verb and resource. It distinguishes from siblings by noting it is a starting point for discovery before querying or scanning, and the 'When to use' section explicitly contrasts with describe_table, query_table, and scan_table.

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

  Usage Guidelines5/5

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

  The description provides an explicit 'When to use' section listing two concrete scenarios (discover tables, find a table name before using other tools). This clearly tells the agent when to use this tool versus alternatives, with no ambiguity.

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

• query_tableA
  4.6/5.0
  Behavior5/5

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

  Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses valuable behavioral traits: results are 'returned sorted by sort key,' filter expressions 'don't reduce read capacity consumed,' and the return includes 'count, scanned_count, and pagination key.' These details are not present in the annotations and help the agent anticipate behavior and side effects.

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

  Conciseness5/5

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

  The description is well-organized with clear sections for purpose, efficiency, usage, and return values. It is concise—each sentence delivers useful information, and the use of bullet points improves scannability without unnecessary verbosity.

  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 tool with a complex input schema (wrapped single parameter object containing multiple fields) and rich annotations, the description covers key aspects: when to use, when not to use, sorted results, filter cost, and return payload. It does not elaborate on expression syntax or pagination mechanics, but the schema descriptions and output schema already cover those details, making the description sufficiently complete for agent selection and initial invocation.

  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 adds minimal parameter context beyond the schema; it only mentions that the 'format' parameter controls output and gives a high-level example of key conditions. The input schema itself provides rich, detailed descriptions for every parameter (e.g., key_condition_expression, filter_expression, index_name), so the description does not need to compensate, but it also does not add significant new meaning beyond the schema's own documentation.

  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: 'Query a DynamoDB table using key conditions to find matching items.' It explicitly identifies the resource (DynamoDB table), the action (query), and the mechanism (key conditions), and further distinguishes it from scan_table in the 'When NOT to use' section by naming the alternative.

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

  Usage Guidelines5/5

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

  The description includes dedicated 'When to use' and 'When NOT to use' sections with concrete scenarios, and explicitly points to scan_table as the alternative for full-table searches or when the partition key is unknown. This is clear guidance on selection versus sibling tools.

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

• prune_tableA
  4.7/5.0
  Behavior5/5

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

  The annotations already mark destructiveHint=true and readOnlyHint=false, but the description adds substantial behavioral context: it requires confirm=true, explains that it scans and batch-deletes, warns that omitting filter_expression deletes ALL items permanently, and specifies that the table structure is preserved. No contradictions with annotations exist.

  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 appropriately structured: purpose first, then warnings, then clear usage bullets, and a return summary. Every sentence serves a purpose; the additional length is justified for a destructive operation and does not feel padded.

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

  Completeness5/5

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

  The description is complete for a destructive tool: it states the operation, the safety requirement (confirm=true), what is preserved, what happens without a filter, when to use/avoid it, and what it returns. Combined with the annotations and output schema, the agent has everything needed to select and invoke the tool correctly.

  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?

  While the reported schema coverage is 0%, the nested PruneTableInput schema actually describes all five parameters in detail. The description repeats the key semantics for confirm and filter_expression (e.g., 'Requires confirm=true' and 'If omitted, ALL items are deleted') but does not add new parameter-level meaning beyond the schema fields.

  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 opens with a specific action and resource: 'Delete all items (or filtered items) from a DynamoDB table.' It clarifies the table itself is preserved, distinguishing it from deleting the table or deleting a single item. This clearly separates it from sibling tools like delete_item.

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

  Usage Guidelines5/5

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

  The description provides explicit 'When to use' and 'When NOT to use' sections, enumerating valid use cases like clearing a table or pruning by criteria, and explicitly pointing to delete_item as the alternative for single-item deletion. It also notes that deleting the table itself is unsupported.

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

• scan_tableA
  4.7/5.0
  Behavior5/5

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

  The annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior; the description enhances this by warning that scans consume read capacity proportional to table size regardless of filters and that filters are applied after reads. It also documents the response includes count, scanned_count, and pagination key, adding operational context beyond the safe-read annotation.

  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 well-structured with clear sections for usage, non-usage, and return values. Every sentence serves a purpose, and the total length is appropriate for the tool's complexity.

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

  Completeness5/5

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

  Given the tool's complexity (DynamoDB scan, filtering, pagination) and the strong annotations and schema, the description covers all critical aspects: performance implications, when to use alternatives, and response contents. It also aligns with the output schema's mention of format, making it a complete guide.

  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. It does mention the 'format' parameter and its values (json or markdown), and notes that filter_expression does not reduce read capacity, but it does not explain other parameters like table_name, limit, index_name, exclusive_start_key, or expression attribute placeholders. Since the schema itself provides detailed descriptions for all parameters, the description adds marginal value but not enough to fully cover the low coverage gap, warranting a mid score.

  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 defines the tool's function with 'Scan a DynamoDB table to read all items' and distinguishes it from the sibling tool by explicitly referencing query_table as a more efficient alternative. This makes its purpose specific and non-overlapping.

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

  Usage Guidelines5/5

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

  The description provides explicit 'When to use' and 'When NOT to use' sections, including concrete scenarios such as browsing all items or not knowing the partition key. It also names the alternative tool (query_table) and warns against scanning large tables without filters, giving clear decision criteria.

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

• add_itemA
  4.8/5.0
  Behavior4/5

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

  Beyond the annotations, the description discloses important behavior: it creates a new item or replaces an existing one with the same primary key, and it shows how to prevent overwrites using condition_expression. It also mentions the return value. This adds meaningful context not available from annotations alone.

  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 well-structured with short, focused sections. Every sentence adds value: precise operation, overwrite nuance, usage guidance, and return type. No filler or redundant content.

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

  Completeness5/5

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

  Given the tool's complexity, the description covers the essential aspects: what it does, when to use it, when not to use it, key parameter semantics, and the return value. An output schema exists, so detailed return field documentation is unnecessary.

  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?

  Even though context signals report 0% schema description coverage, the tool description fully compensates by explaining table_name, item (including the requirement to include partition/sort keys), and condition_expression with a concrete example. This gives an agent enough semantic detail to construct valid arguments.

  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 opens with a specific verb+resource: "Add (put) a single item to a DynamoDB table," clearly identifying the action and target. It further distinguishes itself from siblings by explicitly listing when NOT to use it, naming update_item and bulk_add_items as alternatives.

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

  Usage Guidelines5/5

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

  The description provides a dedicated "When to use" and "When NOT to use" section, with concrete alternatives (update_item for partial updates, bulk_add_items for batch operations). This gives an agent clear decision criteria for tool selection.

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

• bulk_add_itemsA
  4.9/5.0
  Behavior5/5

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

  Even though annotations already indicate non-read-only, idempotent, and non-destructive behavior, the description adds substantial context: uses batch_writer, 25-item batches, automatic retries on unprocessed items, flushing, and overwrite semantics for duplicate primary keys. It also discloses the return format. This goes well beyond the annotation hints.

  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 well-structured with a lead sentence, a short technical detail paragraph, bulleted usage guidelines, and a return statement. Every sentence adds value, and there is no verbose filler. It is front-loaded with the primary action and remains readable.

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

  Completeness5/5

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

  For a bulk write tool with output schema and annotations, this description is comprehensive. It covers the operation's purpose, batching behavior, retries, overwrite semantics, exclusions (single item, conditional writes), and return value. Combined with the schema and annotations, an agent has everything needed to correctly invoke and interpret the 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?

  Context signals indicate low schema coverage (0% at top level), so the description must compensate for parameter meaning. It does so by explaining that items are written in batches of 25, that duplicate primary keys overwrite, and that the return is a count. However, it does not explicitly describe the table_name parameter or the exact structure of items beyond primary key requirement. The nested schema does provide descriptions for items and table_name, partially offsetting this gap.

  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 opens with a specific action: 'Add multiple items to a DynamoDB table in efficient batches.' It clearly identifies the resource (DynamoDB table) and the scope (multiple items, batch efficiency). It also differentiates from sibling tools by explicitly referencing add_item for single-item use cases, making the tool's 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 Guidelines5/5

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

  The description provides explicit 'When to use' and 'When NOT to use' sections. It names add_item as the alternative for single items and highlights that conditional writes are unsupported, giving clear boundaries for when bulk_add_items is appropriate. This is exactly the guidance needed for agent selection.

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

• delete_itemA
  4.9/5.0
  Behavior5/5

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

  The description discloses that the item is 'permanently removed,' which goes beyond the destructiveHint annotation by specifying permanence. It also explains the use of condition_expression for existence checks, adding behavioral context. No contradiction with annotations.

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

  Conciseness5/5

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

  The description is well-structured with a clear opening sentence, a note on permanence, and separate usage sections. Each sentence provides value, and the format is easy to scan. It is appropriately sized for the tool's complexity.

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

  Completeness5/5

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

  The description covers the tool's purpose, usage conditions, alternatives, and return value ('JSON confirmation with the deleted item's key'). This is comprehensive given the annotations and schema, leaving no major gaps 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.

  Parameters4/5

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

  The description explicitly mentions condition_expression and its purpose, adding meaning beyond the schema. It also references 'primary key' and 'DynamoDB table,' which aligns with key and table_name parameters. However, it doesn't elaborate on all parameters, relying partly on the schema's existing 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 clearly states the tool's function: 'Delete a single item from a DynamoDB table by its primary key.' It uses a specific verb (delete) and resource (single item), and distinguishes from sibling tools by emphasizing 'single item' and 'primary key.'

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

  Usage Guidelines5/5

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

  The description includes explicit 'When to use' and 'When NOT to use' sections. It advises using prune_table for deleting all items and scanning first for non-key attributes, providing clear alternatives and exclusions.

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