Server Quality Checklist

Tool Scores

• scan_tableC
  2.7/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 full burden. It mentions scanning with filters but doesn't disclose critical behavioral traits: whether this is a read-only operation, performance implications of scanning entire tables, pagination behavior, error conditions, or authentication requirements. For a table scanning operation with no annotation coverage, this leaves significant gaps in understanding tool behavior.

  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 extremely concise - a single sentence that communicates the core functionality efficiently. Every word earns its place: 'Scans' (action), 'entire table' (resource and scope), 'with optional filters' (key capability). No wasted words or unnecessary elaboration.

  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?

  Given this is a database scanning operation with 5 parameters, no annotations, and no output schema, the description is insufficiently complete. It doesn't explain what scanning returns, performance implications, error handling, or how this differs from query operations. For a potentially resource-intensive table operation, more context about behavior and limitations is needed.

  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 100%, so the schema already documents all 5 parameters thoroughly. The description adds minimal value beyond the schema - it mentions 'optional filters' which aligns with filterExpression, expressionAttributeNames, and expressionAttributeValues parameters, but doesn't provide additional context about filter syntax, performance tradeoffs, or relationship between parameters. Baseline 3 is appropriate when schema does the heavy lifting.

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

  Purpose3/5

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

  The description 'Scans an entire table with optional filters' clearly states the verb ('scans') and resource ('table'), but is somewhat vague about scope ('entire' vs 'filtered') and doesn't distinguish from sibling tools like 'query_table' or 'get_item'. It provides basic purpose but lacks specificity about what scanning entails compared to alternatives.

  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 provided about when to use this tool versus alternatives like 'query_table' or 'get_item'. The description mentions 'optional filters' but doesn't explain when filtering is appropriate or what distinguishes scanning from querying. Without usage context, the agent must infer based on tool names alone.

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

• create_gsiC
  2.9/5.0
  Behavior2/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 but provides minimal information. It states this is a creation operation but doesn't mention whether this requires specific permissions, whether it's a synchronous or asynchronous operation, what happens if the index already exists, or any rate limits or costs associated. For a complex database operation with 10 parameters, this is inadequate 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?

  The description is extremely concise - a single sentence that directly states the tool's purpose without any unnecessary words. It's front-loaded with the core action and resource. Every word earns its place, making this an excellent example of efficient communication.

  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 complex database operation with 10 parameters, no annotations, and no output schema, the description is insufficiently complete. It doesn't explain what a global secondary index is, when one would use it, what the operation returns, or how it differs from local secondary indexes. The agent would need to infer too much from the bare description and parameter names alone.

  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 description coverage is 100%, with all parameters well-documented in the input schema. The description adds no additional parameter information beyond what's already in the structured schema. According to the scoring rules, when schema coverage is high (>80%), the baseline is 3 even with no parameter information in the description.

  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 ('creates') and resource ('global secondary index on a table'), making the purpose immediately understandable. However, it doesn't differentiate this from the sibling tool 'create_lsi' (local secondary index), which would be important context for an AI agent choosing between similar tools.

  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 about when to use this tool versus alternatives. With sibling tools like 'create_lsi', 'create_table', and 'update_gsi' available, the agent receives no help in determining which tool is appropriate for different scenarios. There's no mention of prerequisites, constraints, or typical use cases.

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

• create_lsiC
  2.9/5.0
  Behavior2/5

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

  With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a creation operation (implying mutation) and mentions a timing constraint, but lacks details on permissions required, whether the operation is reversible, error conditions, or what happens to existing data. For a complex 10-parameter mutation tool, this is inadequate.

  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, efficient sentence that states the core purpose and key constraint without unnecessary words. It's appropriately sized and front-loaded with the essential information.

  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 complex database index creation tool with 10 parameters, no annotations, and no output schema, the description is insufficient. It lacks information about what the tool returns, error handling, permissions needed, or how it interacts with sibling tools like 'create_table'. The timing constraint is helpful but doesn't compensate for other 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?

  Schema description coverage is 100%, providing detailed documentation for all 10 parameters. The description adds no parameter-specific information beyond what's in the schema, so it meets the baseline of 3. However, it doesn't explain relationships between parameters (e.g., how projectionType relates to nonKeyAttributes).

  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 ('Creates a local secondary index') and the resource ('on a table'), with specific mention of the constraint 'must be done during table creation'. However, it doesn't explicitly differentiate from sibling 'create_gsi' (global secondary index), which is a closely related alternative.

  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 a critical constraint ('must be done during table creation'), which implies when to use it, but offers no explicit guidance on when to choose this tool over alternatives like 'create_gsi' or 'create_table'. No prerequisites or exclusions are mentioned beyond the timing constraint.

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

• create_tableC
  2.9/5.0
  Behavior2/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 mentions 'specified configuration' but fails to explain critical behaviors like whether this is a mutating operation, what permissions are required, if it's idempotent, or what happens on conflicts. For a creation tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.

  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, efficient sentence that directly states the tool's function without unnecessary words. It's appropriately sized and front-loaded, making it easy to understand quickly with zero wasted content.

  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 complex table creation tool with 7 parameters, no annotations, and no output schema, the description is inadequate. It doesn't explain what the tool returns, error conditions, or behavioral nuances, leaving too much unspecified for proper agent usage despite the comprehensive parameter schema.

  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 description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds no additional parameter semantics beyond implying configuration is needed, which doesn't provide value beyond what the schema offers. This meets the baseline for high schema coverage.

  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 ('Creates') and resource ('new DynamoDB table'), making the purpose evident. However, it doesn't differentiate from sibling tools like 'create_gsi' or 'create_lsi' that also create DynamoDB structures, leaving some ambiguity about when to choose this specific tool.

  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 like 'create_gsi' or 'create_lsi', nor does it mention prerequisites or context for table creation. It simply states what it does without indicating appropriate scenarios or exclusions.

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

• describe_tableC
  2.9/5.0
  Behavior2/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 states this is a read operation ('Gets'), implying it's non-destructive, but doesn't mention authentication requirements, rate limits, error conditions, or what 'detailed information' includes (e.g., schema, throughput, status). For a tool with zero annotation coverage, this leaves significant 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, efficient sentence with zero wasted words. It's front-loaded with the core purpose and appropriately sized for a simple tool. Every word earns its place without being overly terse or verbose.

  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?

  Given the lack of annotations and output schema, the description is incomplete. It doesn't explain what 'detailed information' entails (e.g., table properties, indexes, status), which is critical for a metadata tool. With no behavioral context and minimal parameter guidance, it fails to provide enough information for effective agent use despite the simple schema.

  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 100%, with the single parameter 'tableName' clearly documented in the schema. The description adds no additional parameter semantics beyond what's in the schema—it doesn't clarify format constraints, naming conventions, or examples. The baseline score of 3 reflects adequate coverage when the schema does the heavy lifting.

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

  Purpose4/5

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

  The description clearly states the verb ('Gets') and resource ('detailed information about a DynamoDB table'), making the purpose understandable. It distinguishes this from siblings like 'list_tables' (which lists table names) and 'create_table' (which creates tables), but doesn't explicitly differentiate from other read operations like 'get_item' or 'query_table' beyond the resource scope.

  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 doesn't mention when to choose 'describe_table' over 'list_tables' for metadata, or how it differs from 'get_item' or 'query_table' for data retrieval. There are no prerequisites, exclusions, or contextual usage hints provided.

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

• get_itemC
  2.9/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 states the tool retrieves an item, implying a read-only operation, but doesn't specify whether it returns null for missing keys, requires specific permissions, has rate limits, or details the return format (e.g., JSON object). For a read tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.

  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, efficient sentence that front-loads the core action ('retrieves an item') and includes essential details ('from a table by its primary key'). There is no wasted text, making it highly concise and well-structured for quick understanding.

  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?

  Given the complexity of database operations, no annotations, and no output schema, the description is incomplete. It doesn't explain what happens if the key doesn't exist, the return format, error conditions, or how it differs from sibling tools like 'query_table'. For a tool with 2 parameters and rich sibling context, more detail is needed to fully guide an agent.

  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 100%, with clear descriptions for both parameters ('key' as primary key and 'tableName' as table name). The description adds minimal value beyond the schema by mentioning 'by its primary key,' which reinforces the schema's 'key' parameter but doesn't provide additional syntax or format details. Baseline 3 is appropriate when the schema does the heavy lifting.

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

  Purpose4/5

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

  The description clearly states the tool's purpose with a specific verb ('retrieves') and resource ('item from a table'), specifying it uses the primary key. It distinguishes from siblings like 'put_item' (create) or 'update_item' (modify) by focusing on retrieval, though it doesn't explicitly contrast with 'query_table' or 'scan_table' for alternative lookup methods.

  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 like 'query_table' or 'scan_table', which also retrieve items but with different methods (e.g., by query conditions or full scans). It lacks context on prerequisites, such as needing an existing table, or exclusions, like not supporting secondary indexes.

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

• list_tablesC
  2.9/5.0
  Behavior2/5

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

  With no annotations provided, the description carries full burden but only states the basic function. It doesn't disclose behavioral traits like pagination behavior (implied by parameters but not explained), rate limits, authentication requirements, or what the output format looks like. This leaves significant gaps for an agent to understand how the tool behaves.

  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, efficient sentence that directly states the tool's purpose without unnecessary words. It is front-loaded and wastes no space, making it easy for an agent to parse quickly.

  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?

  Given the tool's moderate complexity (listing resources with pagination), lack of annotations, and no output schema, the description is incomplete. It fails to cover key aspects like output format, error handling, or integration with sibling tools, leaving the agent with insufficient context for reliable use.

  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 has 100% description coverage, clearly documenting both optional parameters for pagination and limits. The description adds no additional parameter semantics beyond what the schema provides, so it meets the baseline of 3 for adequate but not enhanced coverage.

  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 ('Lists') and resource ('all DynamoDB tables in the account'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'describe_table' or 'scan_table', which prevents a perfect score.

  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 like 'describe_table' for detailed table information or 'scan_table' for data retrieval. It lacks context about prerequisites, such as requiring AWS permissions, or when listing tables is appropriate in a workflow.

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

• put_itemC
  2.9/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 states the tool 'Inserts or replaces an item', implying a mutation operation, but fails to detail critical aspects like permissions needed, whether the operation is idempotent, error handling, or side effects. This is a significant gap for a mutation tool with zero annotation coverage.

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

  Conciseness5/5

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

  The description is a single, efficient sentence that directly states the tool's function without unnecessary words. It is appropriately sized and front-loaded, making it easy to understand at a glance.

  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 mutation tool with no annotations, no output schema, and incomplete behavioral details, the description is inadequate. It does not explain return values, error conditions, or how 'inserts or replaces' differs from other operations, leaving the agent with insufficient context for reliable use.

  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 100%, with both parameters ('item' and 'tableName') documented in the schema. The description adds no additional meaning beyond what the schema provides, such as format details or constraints. Given the high schema coverage, a baseline score of 3 is appropriate.

  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 ('Inserts or replaces') and the resource ('an item in a table'), making the purpose understandable. However, it does not explicitly differentiate this tool from sibling tools like 'update_item' or 'create_table', which might handle similar operations, so it misses the highest score.

  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 such as 'update_item' or 'create_table'. It lacks context about prerequisites, exclusions, or specific scenarios, leaving the agent to infer usage based on the name alone.

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

• query_tableC
  2.9/5.0
  Behavior2/5

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

  With no annotations provided, the description carries full burden but offers minimal behavioral context. It doesn't disclose whether this is a read-only operation, what permissions are required, how results are returned (pagination, format), error conditions, or performance characteristics. The mention of 'optional filters' hints at filtering capability but lacks detail.

  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, efficient sentence that communicates the core functionality without unnecessary words. It's front-loaded with the main action and resource, making it immediately understandable.

  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 database query tool with 6 parameters, no annotations, and no output schema, the description is inadequate. It doesn't explain what the tool returns, error handling, authentication requirements, or how it differs from similar operations. The context signals indicate significant complexity that isn't addressed.

  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 100%, so the schema already documents all 6 parameters thoroughly. The description adds marginal value by mentioning 'key conditions' (mapping to keyConditionExpression) and 'optional filters' (mapping to filterExpression), but doesn't provide additional semantic context beyond what's in the schema descriptions.

  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 ('Queries') and resource ('a table'), specifying it uses 'key conditions and optional filters'. This distinguishes it from siblings like 'scan_table' (full table scan) and 'get_item' (single item retrieval), though it doesn't explicitly name these alternatives.

  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 like 'scan_table' or 'get_item'. It mentions 'key conditions' which implies it's for indexed queries, but doesn't state this explicitly or provide any exclusion criteria or prerequisites.

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

• update_capacityC
  2.9/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 states 'Updates' implies a mutation, but doesn't disclose critical traits like required permissions, whether changes are reversible, potential costs or rate limits, or what happens if invalid capacity values are provided. This is a significant gap for a mutation tool with zero annotation coverage.

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

  Conciseness5/5

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

  The description is a single, efficient sentence with zero waste, front-loaded with the core action. It's appropriately sized for the tool's complexity, making it easy to parse quickly without unnecessary elaboration.

  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?

  Given the tool's complexity as a mutation operation with no annotations and no output schema, the description is incomplete. It lacks information on behavioral aspects (e.g., side effects, error handling) and doesn't explain what the tool returns, leaving the agent with insufficient context for reliable use.

  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 no meaning beyond what the input schema provides, as schema description coverage is 100% with clear parameter descriptions. The baseline score of 3 is appropriate because the schema does the heavy lifting, but the description doesn't compensate with additional context like units of capacity or constraints on values.

  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 verb ('Updates') and resource ('provisioned capacity of a table'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'update_gsi' or 'update_item', which might also involve updates to table-related resources, leaving some ambiguity about scope.

  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 doesn't mention prerequisites (e.g., the table must exist), exclusions (e.g., cannot be used with certain table types), or related tools like 'create_table' or 'describe_table' for context, leaving the agent to infer usage from the name alone.

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

• update_gsiC
  2.9/5.0
  Behavior2/5

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

  With no annotations provided, the description carries full burden for behavioral disclosure. It states this is an update operation but doesn't mention whether this requires specific permissions, whether it's a destructive change, what happens to existing capacity settings, rate limits, or what the response looks like. For a capacity management tool with zero annotation coverage, this leaves significant 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, efficient sentence that gets straight to the point with zero wasted words. It's appropriately sized for what it communicates and is perfectly front-loaded with the essential information.

  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 capacity update tool with no annotations and no output schema, the description is insufficient. It doesn't explain what 'provisioned capacity' means in practical terms, what units are used, whether changes are immediate or gradual, what validation occurs, or what happens on failure. The context signals show this is a 4-parameter mutation tool that needs more behavioral context.

  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 description coverage is 100%, so all parameters are documented in the input schema. The description doesn't add any additional parameter context beyond what's already in the schema properties. It mentions 'provisioned capacity' which aligns with the readCapacity and writeCapacity parameters, but provides no extra semantic value.

  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 ('Updates') and the resource ('provisioned capacity of a global secondary index'), making the purpose immediately understandable. It doesn't explicitly differentiate from siblings like 'update_capacity' or 'update_item', but the specificity of 'global secondary index' provides some implicit distinction.

  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 like 'update_capacity' or 'create_gsi'. It doesn't mention prerequisites, dependencies, or scenarios where this operation is appropriate versus other update operations.

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

• update_itemC
  2.9/5.0
  Behavior2/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 mentions 'Updates' which implies mutation, but fails to describe critical behaviors: whether this is idempotent, what happens if the item doesn't exist, what permissions are required, whether changes are reversible, or what the response format looks like. For a mutation tool with zero annotation coverage, this is a significant gap.

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

  Conciseness5/5

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

  The description is a single, efficient sentence that gets straight to the point without any wasted words. It's appropriately sized for the tool's complexity and front-loads the core functionality.

  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 mutation tool with 7 parameters (including complex nested objects), no annotations, and no output schema, the description is inadequate. It doesn't explain the return values, error conditions, or the behavioral implications of the update operation. The agent would need to rely heavily on the schema alone, missing important contextual information about how this tool behaves in practice.

  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 description coverage is 100%, so all parameters are documented in the schema itself. The description adds minimal value beyond what's in the schema - it mentions 'specific attributes' which aligns with the updateExpression parameter, but doesn't provide additional context about parameter relationships or usage patterns. The baseline of 3 is appropriate when the schema does the heavy lifting.

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

  Purpose4/5

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

  The description clearly states the verb ('Updates') and resource ('specific attributes of an item in a table'), making the purpose understandable. However, it doesn't explicitly differentiate this from sibling tools like 'put_item' (which might create/replace items) or 'update_capacity' (which modifies table capacity), leaving some ambiguity about when to choose this specific update tool.

  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 like 'put_item' (for full item replacement) or 'update_capacity' (for table-level changes). It lacks context about prerequisites (e.g., requires existing item), exclusions, or typical scenarios, leaving the agent to infer usage from the tool name alone.

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