Petstore MCP Server

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

No annotations are provided, so the description carries full burden. It implies a write operation ('Add') but does not disclose behavioral traits such as required permissions, whether it's idempotent, error handling, or response format. This is inadequate 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.

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

The description is repetitive ('Add a new pet to the store. - Add a new pet to the store.'), wasting space without adding value. It is under-specified rather than concise, as it lacks necessary details for effective tool use.

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

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

Given the complexity (2 parameters with nested objects, 0% schema coverage, no annotations, no output schema), the description is completely inadequate. It does not explain the tool's purpose beyond the name, parameters, behavior, or output, failing to provide essential context for a mutation tool.

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

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

Schema description coverage is 0%, and the description provides no information about parameters. It does not mention the required 'addPetBody' object, its fields like 'name' and 'photoUrls', or optional ones like 'status'. The description fails to compensate for the lack of schema documentation.

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

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

The description states 'Add a new pet to the store' which is a tautology of the tool name 'addPet' and repeats itself in the same sentence. It provides a basic verb+resource but lacks specificity about what constitutes a pet or distinguishes it from similar tools like 'updatePet' or 'placeOrder' (which might involve pets).

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

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

No guidance is provided on when to use this tool versus alternatives like 'updatePet' or 'createUser'. The description does not mention prerequisites, exclusions, or context for usage, leaving the agent with no direction on selection among siblings.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the authorization requirement ('logged in user'), which is valuable. However, it doesn't describe what happens after creation, whether the operation is idempotent, what validation occurs, or what errors might occur - significant gaps for a mutation tool.

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

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

The description is extremely concise with just two short sentences that communicate the core purpose and key constraint. Every word earns its place with no wasted text.

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

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

For a user creation tool with no annotations, no output schema, 0% schema description coverage, and complex nested parameters, the description is inadequate. It covers authorization but misses parameter guidance, behavioral details, and output expectations - leaving the agent with insufficient information to use this tool effectively.

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

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

Schema description coverage is 0% and there are 2 parameters (one being a complex nested object with 8 properties). The description provides zero information about parameters - no mention of what fields are required, what 'createUserBody' contains, or what 'x-hapi-auth-state' represents. This fails to compensate for the complete lack of schema documentation.

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

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

The description states 'Create user' which is a clear verb+resource combination, but it's overly generic and doesn't differentiate from sibling tools like 'createUsersWithListInput' or 'updateUser'. It doesn't specify what kind of user is being created or in what context.

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

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

The description provides explicit context for when to use this tool: 'This can only be done by the logged in user.' This gives clear authorization guidance. However, it doesn't specify when to choose this over 'createUsersWithListInput' or other user-related tools.

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

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

No annotations are provided, so the description carries full burden for behavioral disclosure. The description only states the action ('creates') without any information about permissions required, whether this is idempotent, what happens on partial failures, rate limits, or what the response contains. For a batch creation tool with zero annotation coverage, this is completely inadequate.

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

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

The description is technically concise but suffers from severe under-specification. The exact same phrase is repeated twice ('Creates list of users with given input array. - Creates list of users with given input array.'), which is wasteful rather than helpful. While brief, it fails to provide necessary information, making this poor structure rather than effective conciseness.

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

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

This is a batch creation tool with 2 parameters, no annotations, no output schema, and 0% schema description coverage. The description provides only the most basic action statement without any context about authentication, error handling, response format, or system behavior. For this level of complexity and lack of structured documentation, the description is completely inadequate.

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

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

Schema description coverage is 0%, meaning none of the 2 parameters are documented in the schema. The description provides no information about parameters whatsoever - it doesn't mention the 'x-hapi-auth-state' header or the 'createUsersWithListInputBody' array structure. For a tool with 2 undocumented parameters, the description adds zero semantic value.

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

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

The description states 'Creates list of users with given input array' which is a tautology that essentially restates the tool name. While it does specify the verb ('creates') and resource ('users'), it lacks specificity about what kind of users or system context, and doesn't distinguish from sibling 'createUser' which appears to create single users. The repetition in the description adds no clarity.

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

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

No guidance is provided about when to use this tool versus alternatives. There's no mention of prerequisites, when batch creation is appropriate versus single-user creation (createUser), or any contextual constraints. The description offers zero usage guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It indicates this is a destructive operation ('Delete') and specifies error conditions for invalid inputs, which adds useful context. However, it lacks details on permissions, side effects, or response format, leaving gaps in behavioral understanding.

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

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

The description is front-loaded with the core purpose and efficiently follows with critical usage details in two sentences. Every sentence earns its place by providing essential information without redundancy, making it highly concise and well-structured.

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

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

Given the complexity of a destructive operation with no annotations and no output schema, the description is adequate but incomplete. It covers input validation and errors well, but lacks information on authentication needs, success responses, or broader behavioral traits, which are important for a deletion tool.

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

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

The schema description coverage is 0%, so the description must compensate. It explains the semantics of the 'orderId' parameter by specifying valid ranges and error conditions, which adds significant value beyond the bare schema. It doesn't mention the optional 'x-hapi-auth-state' parameter, but the coverage for the required parameter is strong.

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

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

The description clearly states the verb ('Delete') and resource ('purchase order by identifier'), making the purpose specific and understandable. However, it doesn't explicitly distinguish this tool from sibling tools like 'deletePet' or 'deleteUser' beyond the resource type, 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.

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

The description provides clear context on when to use this tool by specifying valid inputs ('integer IDs with value < 1000') and warnings about errors for invalid inputs. It doesn't explicitly mention alternatives or when not to use it, but the guidance is practical and helpful for correct invocation.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the action ('deletes') without mentioning permissions needed, whether deletion is permanent/reversible, rate limits, error conditions, or what happens on success. This is inadequate for a destructive operation.

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

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

The description is technically concise but inefficiently structured. 'Deletes a pet. - Delete a pet.' is redundant rather than informative. It wastes space on repetition instead of providing useful context about the tool's behavior or parameters.

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

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

For a destructive operation with 3 parameters, 0% schema coverage, no annotations, and no output schema, the description is completely inadequate. It doesn't explain what the tool does beyond the basic action, provides no parameter guidance, and offers no behavioral context about this potentially significant mutation.

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

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

Schema description coverage is 0%, so the schema provides no parameter documentation. The description offers no information about the 3 parameters (petId, api_key, x-hapi-auth-state) - not their purposes, formats, or which are required. This leaves parameters completely undocumented.

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

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

The description states 'Deletes a pet' which is a clear verb+resource combination, but it's repetitive with '- Delete a pet.' and doesn't distinguish from sibling tools like 'deleteOrder' or 'deleteUser'. It's vague about what constitutes a 'pet' in this context.

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

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

No guidance is provided about when to use this tool versus alternatives. There's no mention of prerequisites (e.g., needing a valid petId), when not to use it, or how it differs from other deletion tools like 'deleteOrder' or 'deleteUser'.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the authentication requirement, which is crucial for a destructive operation. However, it doesn't specify whether deletion is permanent/reversible, what happens to associated data, or any rate limits/error conditions, leaving 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.

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

The description is extremely concise with just two sentences that both add value. The first states the core purpose, the second adds critical authentication context. There's zero wasted language or redundancy.

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

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

For a destructive operation with no annotations and no output schema, the description is insufficient. It doesn't explain what happens upon successful deletion, what errors might occur, or provide complete parameter guidance. The authentication note helps but doesn't compensate for other critical missing context.

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

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

With 0% schema description coverage for 2 parameters, the description provides no information about the 'username' parameter (what format, constraints) or the optional 'x-hapi-auth-state' parameter. The description doesn't compensate for the complete lack of parameter documentation in the schema.

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

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

The description clearly states the action ('Delete') and resource ('user resource'), making the purpose immediately understandable. However, it doesn't differentiate from sibling deletion tools like deleteOrder or deletePet, which would require mentioning the specific resource type.

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

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

The description provides clear context about who can use this tool ('only by the logged in user'), which is valuable guidance. It doesn't explicitly state when to use this versus alternatives like updateUser or when not to use it, but the authentication constraint is a strong usage indicator.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions that multiple status values can be provided with comma-separated strings, which is a behavioral trait. However, it lacks critical details: whether this is a read-only operation, if it requires authentication (implied by 'x-hapi-auth-state' parameter), what the return format is, or any rate limits. The description is insufficient for a tool with potential auth needs.

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

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

The description is concise and front-loaded, with two sentences that directly address the tool's function and parameter usage. There is no wasted text, and it efficiently conveys key information. It could be slightly improved by structuring it more clearly (e.g., separating purpose from parameter details).

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

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

Given the complexity (2 parameters, no annotations, no output schema), the description is incomplete. It covers basic parameter usage but misses authentication requirements (implied by 'x-hapi-auth-state'), return values, error handling, and differentiation from sibling tools. For a filtering tool with potential auth and multiple siblings, this leaves significant gaps.

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

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

The description adds meaningful semantics beyond the input schema. The schema has 0% description coverage and only defines 'status' as an enum and 'x-hapi-auth-state' as a string. The description clarifies that 'status' accepts multiple values via comma-separated strings, which isn't evident from the enum alone. However, it doesn't explain 'x-hapi-auth-state'. With 2 parameters and low schema coverage, the description partially compensates.

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

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

The description states the tool's purpose ('Finds Pets by status') which is clear but vague. It specifies the resource (Pets) and filtering criterion (status), but doesn't distinguish it from sibling 'findPetsByTags' which also filters pets. The description lacks specificity about what 'finds' entails (e.g., returns a list).

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

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

No guidance is provided on when to use this tool versus alternatives. It doesn't mention sibling tools like 'findPetsByTags' (which filters by tags) or 'getPetById' (which retrieves a single pet), nor does it specify prerequisites or exclusions. The description only explains parameter syntax without contextual usage.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions that multiple tags can be provided with comma-separated strings, which adds some context about input format. However, it fails to describe critical behaviors such as whether this is a read-only operation, how results are returned (e.g., list format, pagination), error handling, or authentication needs (implied by the 'x-hapi-auth-state' parameter). The description is insufficient for a tool with no annotation coverage.

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

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

The description is concise and front-loaded, starting with the core purpose. The second sentence adds necessary input format details, and the third provides a testing example, which is somewhat extraneous but not wasteful. Overall, it is efficiently structured with minimal fluff.

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

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

Given the complexity (a search tool with 2 parameters, no annotations, and no output schema), the description is incomplete. It covers the basic purpose and input format for one parameter but misses authentication details, output behavior, and error handling. Without annotations or an output schema, more comprehensive guidance is needed for effective agent use.

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

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

Schema description coverage is 0%, so the description must compensate for undocumented parameters. It explains the 'tags' parameter by stating 'Multiple tags can be provided with comma separated strings' and gives an example, adding meaning beyond the schema. However, it completely ignores the 'x-hapi-auth-state' parameter, leaving it unexplained. With 2 parameters and only partial coverage, the description does not fully compensate for the schema gap.

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

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

The description clearly states the tool's purpose: 'Finds Pets by tags.' It specifies the verb ('Finds') and resource ('Pets'), with the scope being tag-based filtering. However, it does not explicitly differentiate from sibling tools like 'findPetsByStatus', which filters by status instead of tags, leaving some ambiguity.

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

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

The description implies usage by specifying that it finds pets using tags, but it does not provide explicit guidance on when to use this tool versus alternatives like 'findPetsByStatus' or 'getPetById'. It mentions a testing example ('Use tag1, tag2, tag3 for testing'), which hints at context but lacks clear when-to-use or when-not-to-use statements.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the return type ('map of status codes to quantities'), which is helpful, but lacks critical details: it doesn't specify authentication needs (implied by the 'x-hapi-auth-state' parameter in the schema), rate limits, error conditions, or whether it's read-only (implied by 'returns' but not explicit). For a tool with no annotations, 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.

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

The description is concise and front-loaded: the first sentence states the core purpose, and the second adds return format details. Both sentences earn their place by providing essential information without redundancy. However, it could be slightly more structured (e.g., separating purpose from output details more clearly), preventing a perfect score.

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

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

Given the tool's moderate complexity (inventory retrieval with a parameter), no annotations, no output schema, and low schema coverage, the description is incomplete. It covers the basic purpose and return format but misses parameter explanations, authentication context, and usage scenarios. Without annotations or output schema, the description should do more to compensate, but it falls short.

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

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

The input schema has one parameter ('x-hapi-auth-state') with 0% schema description coverage, meaning the schema provides no details about this parameter. The description adds no information about parameters—it doesn't mention 'x-hapi-auth-state' or explain its purpose (e.g., authentication state). Since the description must compensate for low schema coverage but fails to do so, the score is low.

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

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

The description clearly states the tool's purpose: 'Returns pet inventories by status' specifies the verb (returns) and resource (pet inventories), with the additional detail 'by status' providing scope. It distinguishes from siblings like 'findPetsByStatus' (which returns pets, not inventory quantities) and 'getPetById' (which returns a single pet). However, it doesn't explicitly differentiate from all siblings, keeping it from 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.

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, context for inventory retrieval, or compare it to other inventory-related tools (none exist in siblings, but general alternatives aren't addressed). The agent must infer usage from the purpose alone, which is insufficient for clear decision-making.

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

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

No annotations are provided, so the description carries the full burden. It discloses that invalid IDs 'will generate exceptions,' which is useful behavioral context about error handling. However, it doesn't mention other traits like whether this is a read-only operation, authentication requirements (though x-hapi-auth-state parameter hints at this), rate limits, or response format. The description adds some value but leaves gaps for a tool with no annotation coverage.

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

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

The description is extremely concise and front-loaded: the first sentence states the core purpose, and the second adds critical usage guidance. Every sentence earns its place with no wasted words, 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.

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

Given no annotations, 0% schema coverage, 2 parameters, and no output schema, the description is moderately complete. It covers the tool's purpose and key usage constraints but misses details on the second parameter, authentication, response format, and error specifics beyond exceptions. For a simple lookup tool, this is adequate but has clear gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'integer IDs' for the orderId parameter, adding semantic context about data type and constraints (values <=5 or >10). However, it doesn't address the x-hapi-auth-state parameter at all, leaving half of the parameters undocumented. The description provides partial compensation but not enough for the coverage gap.

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

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

The description clearly states the tool's purpose: 'Find purchase order by ID' specifies the verb ('find') and resource ('purchase order'), with the ID parameter implied. It distinguishes from siblings like getInventory or getPetById by focusing on orders, but doesn't explicitly differentiate from placeOrder or deleteOrder in terms of read vs. write operations.

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

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

The description provides clear usage guidance: 'For valid response try integer IDs with value <= 5 or > 10. Other values will generate exceptions.' This tells the agent when to use it (for specific ID ranges) and warns about invalid inputs. However, it doesn't explicitly mention when to use this tool versus alternatives like getInventory for other data or placeOrder for creating orders.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool returns a single pet, which is useful, but lacks critical details such as error handling (e.g., if the pet ID doesn't exist), authentication needs (implied by 'x-hapi-auth-state' parameter), or rate limits. This leaves significant gaps in understanding the tool's behavior.

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

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

The description is concise and front-loaded, with two short sentences that directly state the tool's action and output. There's no wasted verbiage, though it could be slightly more structured (e.g., separating usage notes).

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

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

Given the complexity (a read operation with 2 parameters, no output schema, and no annotations), the description is incomplete. It lacks details on authentication, error cases, return format beyond 'a single pet', and how it differs from sibling tools, making it inadequate for safe and effective use by an agent.

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

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

Schema description coverage is 0%, so the description must compensate for undocumented parameters. It mentions 'petId' implicitly but doesn't explain its semantics (e.g., what constitutes a valid ID) or address the optional 'x-hapi-auth-state' parameter at all. This fails to add meaningful context beyond the bare schema.

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

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

The description clearly states the tool's purpose with a specific verb ('Find') and resource ('pet by ID'), and distinguishes it from siblings like 'findPetsByStatus' or 'findPetsByTags'. However, it doesn't explicitly differentiate from 'getOrderById' or 'getUserByName' in terms of resource type, which slightly limits clarity.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a pet ID), exclusions, or comparisons to siblings like 'findPetsByStatus' for broader searches, leaving the agent to infer usage context.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the basic action ('Get user') without detailing traits like authentication requirements (suggested by 'x-hapi-auth-state'), rate limits, error handling, or what 'user detail' includes. For a tool with no annotation coverage, this leaves significant gaps in understanding its behavior and constraints.

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

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

The description is brief but inefficiently structured: it repeats the same idea ('Get user by user name. - Get user detail based on username.') with slight variation, wasting space. It is front-loaded with the core purpose, but the redundancy reduces conciseness. A single, clear sentence would be more effective, though it avoids excessive verbosity.

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

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

Given the tool's complexity (2 parameters, no annotations, no output schema), the description is incomplete. It lacks details on authentication, response format, error cases, and how it differs from sibling tools. Without an output schema, the description should ideally hint at what 'user detail' includes, but it does not. This leaves the agent with insufficient context for reliable invocation.

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

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

The input schema has 2 parameters with 0% description coverage, meaning the schema provides no semantic information. The description does not compensate by explaining the parameters: it mentions 'username' implicitly but does not define its format or constraints, and ignores 'x-hapi-auth-state' entirely. With low schema coverage, the description adds minimal value beyond the tool's name, failing to clarify parameter meanings.

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

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

The description states the tool's purpose ('Get user by user name' and 'Get user detail based on username'), which is clear but vague. It specifies the verb ('Get') and resource ('user'), but does not distinguish it from potential siblings like 'getUserById' or 'getUserByEmail', which might exist in other contexts. The repetition ('Get user by user name. - Get user detail based on username.') adds redundancy without enhancing clarity.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, such as authentication needs implied by the 'x-hapi-auth-state' parameter, or compare it to sibling tools like 'getUserById' (if it existed) or other user-related operations. Without explicit or implied context for usage, the agent lacks direction on tool selection.

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

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

No annotations are provided, so the description must fully disclose behavioral traits. It only states the action 'logs user into the system' without details on authentication methods, session handling, error responses, rate limits, or security implications. This is inadequate for a login operation with potential side effects.

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

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

The description is brief but inefficiently structured, repeating 'Logs user into the system. - Log into the system.' with redundant phrasing. It is under-specified rather than concise, as it wastes space on repetition instead of providing useful information.

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

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

Given the complexity of a login tool (involving authentication, sessions, security), no annotations, no output schema, and 0% schema coverage, the description is severely incomplete. It lacks essential details on behavior, parameters, outputs, and error handling, making it inadequate for safe and effective use.

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

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

Schema description coverage is 0%, so the description must compensate by explaining parameters. It mentions no parameters, leaving 'username', 'password', and 'x-hapi-auth-state' undocumented. No meaning is added beyond the bare schema, failing to clarify their roles or requirements.

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

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

The description 'Logs user into the system. - Log into the system.' is tautological, essentially restating the tool name 'loginUser' with minor variations. It specifies the verb 'logs' and resource 'user' but lacks differentiation from sibling tools like 'logoutUser' or context about what 'the system' refers to. The repetition adds no clarity.

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

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

No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites (e.g., needing credentials), exclusions (e.g., not for re-authentication), or related tools like 'logoutUser' or 'createUser'. The description offers no context for usage decisions.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool logs out a user session, implying it's a mutation operation, but lacks details on effects (e.g., session invalidation, authentication state changes), permissions required, or error handling. This is a significant gap for a tool with potential security implications.

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

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

The description is brief but includes redundant phrasing ('- Log user out of the system') that adds no value. It is front-loaded with the core action, but the repetition slightly undermines efficiency. Overall, it's concise but could be more structured.

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

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

Given the tool's complexity (a mutation with security implications), no annotations, no output schema, and undocumented parameters, the description is incomplete. It lacks critical details like behavioral effects, return values, or error cases, making it inadequate for safe and effective use by an AI agent.

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

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

The input schema has one parameter ('x-hapi-auth-state') with 0% description coverage, and the tool description provides no information about parameters. This leaves the parameter's purpose, format, and usage completely undocumented, failing to compensate for the schema's lack of detail.

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

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

The description clearly states the tool's purpose with a specific verb ('Logs out') and resource ('current logged in user session'), and it distinguishes itself from sibling tools like loginUser. However, it slightly repeats itself with '- Log user out of the system,' which is redundant but not misleading.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., requiring an active session) or exclusions, leaving the agent to infer usage from context alone.

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

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

With no annotations provided, the description carries full burden but only states it's for placing a new order. It lacks details on behavioral traits such as authentication requirements (implied by 'x-hapi-auth-state' parameter), error handling, or side effects like inventory changes, which are critical for a mutation tool.

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

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

The description is concise with two short sentences that are front-loaded and avoid redundancy. However, the second sentence ('Place a new order in the store.') adds minimal value beyond the first, slightly reducing efficiency.

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

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

Given the complexity (mutation tool with nested parameters, no annotations, no output schema), the description is incomplete. It fails to address key aspects like authentication needs, parameter meanings, or expected outcomes, making it inadequate for safe and effective use by an agent.

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

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

Schema description coverage is 0%, so the description must compensate but adds no parameter information. It doesn't explain the purpose of 'placeOrderBody' (containing petId, quantity, etc.) or 'x-hapi-auth-state', leaving parameters undocumented and their semantics unclear.

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

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

The description clearly states the action ('Place an order') and resource ('for a pet'), with the second sentence reinforcing it's about placing a new order in the store. However, it doesn't explicitly differentiate from sibling tools like 'addPet' or 'updatePet', which could also involve pet-related operations.

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

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

No guidance is provided on when to use this tool versus alternatives. For example, it doesn't specify if this is for creating new orders only (vs. updating existing ones with 'updatePet') or if there are prerequisites like authentication, leaving the agent to infer usage from context.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states this is an update operation, implying mutation, but doesn't cover critical aspects like required permissions, whether changes are reversible, error handling (e.g., if the pet doesn't exist), or rate limits. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.

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

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

The description is brief but inefficiently structured—it repeats the same idea ('Update an existing pet') in two slightly different phrasings, wasting space. It's front-loaded with the core action but lacks follow-up details that would earn its place. While not overly verbose, it could be more concise and informative.

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

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

Given the complexity (mutation tool with 2 parameters, nested objects, no annotations, and no output schema), the description is incomplete. It doesn't explain the update process, required inputs beyond 'Id', potential outcomes, or error scenarios. For a tool that modifies data, this leaves too many gaps for effective agent use.

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

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

Schema description coverage is 0%, so the description must compensate for undocumented parameters. It mentions updating 'by Id', but the input schema includes 'updatePetBody' (with nested properties like name, photoUrls, status) and 'x-hapi-auth-state'. The description doesn't explain what these parameters mean, their formats, or how they interact, failing to add meaningful semantics beyond the bare schema.

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

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

The description states the action ('Update an existing pet') and resource ('pet'), which clarifies the basic purpose. However, it's somewhat vague as it doesn't specify what fields can be updated or how the update works, and it repeats itself ('Update an existing pet. - Update an existing pet by Id.') without adding clarity. It doesn't distinguish from sibling tools like 'updatePetWithForm' or 'addPet'.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing the pet's ID), compare to siblings like 'updatePetWithForm' or 'addPet', or specify use cases. This leaves the agent without context for tool selection.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It states this is an update operation (implying mutation), but doesn't disclose authentication requirements (despite the 'x-hapi-auth-state' parameter in schema), rate limits, whether changes are reversible, or what happens to unspecified fields. The description adds minimal context beyond the obvious 'update' action.

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

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

The description is brief (two short sentences), but the second sentence is essentially redundant with the first, wasting space. While appropriately sized, it could be more efficiently structured by eliminating repetition and providing more meaningful information in the same word count.

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

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

For a mutation tool with 4 parameters, 0% schema coverage, no annotations, and no output schema, the description is inadequate. It doesn't explain what fields can be updated, how the update works, what authentication is needed, or what the tool returns. The minimal description leaves too many gaps for effective tool use.

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

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

Schema description coverage is 0%, so the description must compensate for all 4 parameters. The description mentions 'form data' which implies the parameters might correspond to form fields, but doesn't explain what 'petId', 'name', 'status', or 'x-hapi-auth-state' represent or how they should be used. No parameter-specific guidance is provided beyond the generic 'form data' reference.

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

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

The description states 'Updates a pet in the store with form data' which provides a basic verb+resource, but it's redundant with the second sentence that essentially repeats the same information. It doesn't distinguish this tool from its sibling 'updatePet' (which likely updates via JSON payload rather than form data), making it a tautological restatement rather than clear differentiation.

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

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

No guidance is provided on when to use this tool versus alternatives like 'updatePet'. The description mentions 'form data' which hints at a specific usage context, but it doesn't explicitly state when form-based updates are appropriate versus JSON-based updates, nor does it mention prerequisites or exclusions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the authentication constraint ('logged in user'), which is valuable, but fails to describe other critical behaviors: whether this is a destructive mutation, what happens on success/failure, rate limits, or response format. For a mutation tool with zero annotation coverage, this is insufficient.

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

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

The description is extremely concise with just two brief sentences that are front-loaded and waste no words. Every part earns its place by stating the action and a key constraint efficiently.

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

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

Given the complexity (mutation tool with 3 parameters, nested objects, no output schema, and 0% schema coverage), the description is incomplete. It lacks details on parameter usage, behavioral outcomes, error handling, and return values, making it inadequate for safe and effective tool invocation by an AI agent.

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

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

Schema description coverage is 0%, so the description must compensate for undocumented parameters. It adds no information about the 3 parameters (username, updateUserBody, x-hapi-auth-state) beyond what's implied by the tool name. The description doesn't explain parameter purposes, formats, or relationships, leaving significant gaps in understanding.

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

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

The description clearly states the verb ('Update') and resource ('user resource'), making the purpose immediately understandable. However, it doesn't differentiate this tool from potential sibling update tools (like updatePet) beyond the resource type, missing explicit distinction.

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

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

The description provides clear context for when to use this tool ('This can only be done by the logged in user'), indicating an authentication requirement. However, it doesn't specify when NOT to use it or mention alternatives (e.g., createUser for new users vs. updateUser for existing ones), leaving some guidance gaps.

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

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

No annotations are provided, so the description carries the full burden. It states the action ('Uploads an image') but lacks critical behavioral details: it doesn't specify required permissions (e.g., authentication via 'x-hapi-auth-state'), file format constraints, size limits, error handling, or what happens on success (e.g., returns a URL). For a mutation tool with zero annotation coverage, 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.

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

The description is brief with two short phrases, but it's somewhat redundant ('Uploads an image' and 'Upload image of the pet'). It front-loads the core action but could be more structured (e.g., combining ideas). It avoids excessive verbosity but doesn't maximize efficiency.

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

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

Given the complexity (4 parameters, no annotations, no output schema), the description is incomplete. It doesn't address authentication needs, file handling, response format, or error cases. For a tool that likely involves binary uploads and mutations, more context is needed to guide the agent effectively.

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

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

Schema description coverage is 0%, so the description must compensate for undocumented parameters. It mentions 'image' and 'pet' but doesn't explain the four parameters: 'petId' (required), 'uploadFileBody' (binary data), 'x-hapi-auth-state' (authentication), or 'additionalMetadata' (optional info). The description adds minimal meaning beyond the schema, failing to clarify parameter roles or usage.

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

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

The description states 'Uploads an image' which provides a basic verb+resource, but it's vague about the specific context. The addition '- Upload image of the pet' clarifies the domain but doesn't fully distinguish it from potential siblings like 'updatePetWithForm' which might also handle images. It avoids tautology by not just repeating the name.

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

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

No explicit guidance on when to use this tool versus alternatives is provided. The description implies usage for pet images but doesn't mention prerequisites, exclusions, or how it differs from other pet-related tools like 'updatePet' or 'updatePetWithForm'. The agent must infer context from the sibling list.

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